Building Stripe Plugins and Libraries

    When you’re developing Stripe plugins or libraries for third-party platforms, you should follow these best practices to safely process on our platform. If you have questions along the way, you can reach out to plugins@stripe.com.

    Follow these best practices to ensure that your users can safely process on Stripe’s platform without disruption as our API evolves:

    You can also take a few steps to improve the quality of your plugin or library:

    • Add the Payment Request Button to collect payment and address information from your customers using Apple Pay, Pay with Google, and the Payment Request API
    • Enable multiple payment methods beyond credit cards to support international users
    • Verify your users have HTTPS enabled to improve their security
    • Subscribe to our mailing list to keep up to speed with changes to Stripe’s API

    Identifying your plugin or library

    You must provide some basic identifying information so that we can contact you about future issues or critical updates to the API. To do this, use setAppInfo with a hash containing the following options:

    • appName (required): your library’s name
    • appVersion (optional): your library’s version
    • appUrl (optional): the URL for your library’s website with your contact details
    Stripe.set_app_info(
      "WordPress MyStripePlugin",
      version: "1.2.34",
      url: "https://example.com"
    );
    stripe.set_app_info(
      "WordPress MyStripePlugin",
      version="1.2.34",
      url="https://example.com"
    )
    \Stripe\Stripe::setAppInfo(
      "WordPress MyStripePlugin",
      "1.2.34",
      "https://example.com"
    );
    // This function is currently unavailable in Java.
    // Reach out to us at plugins@stripe.com if you need support.
    stripe.setAppInfo({
      name: "WordPress MyStripePlugin",
      version: "1.2.34",
      url: "https://example.com"
    });
    stripe.SetAppInfo(&stripe.AppInfo{
      Name: "WordPress MyStripePlugin",
      Version: "1.2.34",
      URL: "https://example.com"
    })
    // This function is currently unavailable in .NET.
    // Reach out to us at plugins@stripe.com if you need support.

    Setting the API version

    Stripe’s API changes over time as new features are added and critical bugs are fixed. To help track down bugs and incompatibilities, it’s very important that your Stripe library specifies which version of the API it’s designed to use.

    Your library should use the setApiVersion function, which will set the Stripe-Version HTTP header on all requests. Your users will use their own API keys to access Stripe, but this header will be included with every request. We recommend that you use the most recently published version of the API. The current API version and details on our versioning policy can be found in the API reference.

    Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    Stripe.api_version = "2017-06-05"
    stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    stripe.api_version = "2017-06-05"
    \Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    \Stripe\Stripe::setApiVersion("2017-06-05");
    Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
    Stripe.apiVersion = "2017-06-05";
    const stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    stripe.setApiVersion("2017-06-05");
    // The API version is statically defined in each version of the Go library.
    // The API version is statically defined in each version of the .NET library.

    New Stripe users automatically default to the latest version of the API. This header ensures that your library is pinned to a specific API version, which keeps the occasional backwards-incompatible change from breaking your library’s functionality.

    Users can upgrade their own API version through the Stripe Dashboard. If your library relies on webhook events, their data format and structure depend on the user’s account API version. You should instruct your users to set the version in their Dashboard to match your library.

    Subscribing to our mailing list for updates

    We regularly release new versions of the Stripe API that bring new features and bug fixes. You can subscribe to the plugins-announce mailing list to be notified of updates that may affect users of your plugin or library.

    Securely collecting payment details

    Stripe users are subject to PCI compliance, which specifies how credit card data should be securely stored, processed, and transmitted. Their businesses could face stiff penalties for noncompliance or potential breaches, so it’s important to help them safely process on Stripe.

    Since your library will make API calls on behalf of a Stripe user, you must transmit credit card data securely using client-side tokenization. Customers submit their personal information through their web browser or mobile app directly to Stripe, and in exchange a simple token will be sent to the Stripe user. This allows your users to securely collect card details without sensitive data ever touching their server.

    If your library includes a client-side payment form in the browser, we recommend that you use either Stripe.js and Elements or Checkout:

    • Elements provides pre-built UI components and complete control over the look and feel of payment forms
    • Checkout provides a complete payment widget and can be quickly added to a Stripe user’s website

    Both of these options provide client-side tokenization with a minimum of effort. Additional methods for tokenizing payment information can be found in our documentation.

    If your library only operates in a backend environment, please include a note in your library’s documentation asking users to tokenize payment details using Elements or Checkout. Tokenization helps Stripe users process as safely as possible on our platform.

    Add the Payment Request Button

    The Payment Request Button is a single Element that enables Apple Pay, Pay with Google, and the Payment Request API—a browser standard that lets customers quickly provide payment and address information stored in their browser.

    This Element will show either an Apple Pay or Payment Request button, depending on which device and browser the customer uses. You can see an example in our documentation.

    Enabling multiple payment methods

    Stripe supports multiple payment methods, aside from credit cards. We’ve published a guide to payment methods that introduces terminology, key considerations, and how we support each method on our platform.

    The Sources API enables your users to collect payments using additional payment methods (e.g. Alipay, iDEAL, SOFORT). These payment sources can be quickly added using one integration path. For more information, you can read about best practices to consider when using Sources.

    Verifying that HTTPS is enabled

    If your plugin or library presents a payment form in a web browser, it should check if the form is being served via HTTPS. We require our users to enable HTTPS: you should present a clear error to your user if they’re not properly secured.

    Here are a few examples to verify whether your users have HTTPS enabled:

    # This example uses Sinatra, but the `request` object is provided by Rack
    require 'sinatra'
    
    get '/' do
      if not request.https?
        # Present an error to the user
      end
      # ...
    end
    # This example uses Flask
    from flask import Flask, request
    app = Flask(__name__)
    
    @app.route('/')
    def index():
      if not request.is_secure:
        # Present an error to the user
      # ...
    if (isset($_SERVER['HTTPS'])) {
      // Present an error to the user
    }
    // This example uses Express
    const express = require('express');
    const app = express();
    
    app.get('/', function(request, response) {
      if (!req.secure) {
        // Present an error to the user
      }
    });
    
    app.listen(3000);
    // This example uses Spark
    import spark.Request;
    import static spark.Spark.*;
    
    public class Main {
      public static void main(String[] args) {
        get("/", (req, res) -> {
          if (!isSecure(req)) {
            // Present an error to the user
          }
          // ...
        });
      }
      public static boolean isSecure(Request req) {
        // Check the URL scheme
        if (req.scheme().toLowerCase().equals("https")) {
          return true;
        }
        // Check the headers
        String xForwardedProto = req.headers("X-Forwarded-Proto");
        if (xForwardedProto != null && xForwardedProto.toLowerCase().equals("https")) {
          return true;
        }
        // Check the protocol
        if (req.protocol().startsWith("HTTPS")) {
          return true;
        }
    
        return false;
      }
    }
    // This example uses the built-in net/http package
    package main
    
    import (
      "fmt"
      "net/http"
      "strings"
    )
    
    func isSecure(r *http.Request) bool {
      // Check the URL scheme
      if strings.ToLower(r.URL.Scheme) == "https" {
        return true
      }
      // Check the headers
      if strings.ToLower(r.Header.Get("X-Forwarded-Proto")) == "https" {
        return true
      }
      // Check the protocol
      if strings.HasPrefix(r.Proto, "HTTPS") {
        return true
      }
      // Detect TLS
      if r.TLS != nil {
        return true
      }
      return false
    }
    
    func handler(w http.ResponseWriter, r *http.Request) {
      if !isSecure(r) {
        // Present an error to the user
      }
      // ...
    }
    
    func main() {
      http.HandleFunc("/", handler)
      http.ListenAndServe(":3000", nil)
    }
    // This example works for any ASP.NET Core app (using Microsoft.AspNetCore.Mvc)
    // You can add this to ConfigureServices in the Startup class:
    public void ConfigureServices(IServiceCollection services)
    {
      services.Configure<MvcOptions>(options =>
      {
        options.Filters.Add(new RequireHttpsAttribute());
      });
    }

    If your library has a front-end component, you can check whether HTTPS is being used from the browser. For example, using JavaScript:

    // This example checks for HTTPS from the browser
    if (window.location.protocol != "https:") {
      // Present an error to the user
    }