Sign in
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Quickstart
Stripe CLI
Stripe for Visual Studio Code
Webhooks
File uploads
Error handling
Error codes
API
Keys
Libraries
Upgrades
Rate limits
Card testing
Expanding responses
Domains and IP addresses
Building With Stripe
Stripe's UI libraries
Extensions
Plugins
Samples
Checklist
Developer tools
Libraries
HomeDeveloper tools

API libraries

Stripe has official libraries for different programming languages and mobile platforms. There are also many more third-party libraries and plugins created by the Stripe community.

Client-side & UI libraries

Web iOS Android

Use Stripe on the web with Elements, a set of prebuilt UI components for collecting and validating card details. Elements uses Stripe.js, our foundational JavaScript library for building payment flows.

HTML + JS React

You need to include Stripe.js on your checkout page by either adding the script tag to the head of your HTML file, or importing it from the stripe-js module:

HTML ES Module
<script src="https://js.stripe.com/v3/"></script>
<script src="https://js.stripe.com/v3/"></script>
npm install @stripe/stripe-js
npm install @stripe/stripe-js

Next, create an instance of the Stripe object by providing your publishable API key as the first parameter:

JavaScript JavaScript (ESNext)
var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
import {loadStripe} from '@stripe/stripe-js'; const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
import {loadStripe} from '@stripe/stripe-js'; const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

Finally, create an instance of the Elements UI library:

JavaScript JavaScript (ESNext)
var elements = stripe.elements();
var elements = stripe.elements();
const elements = stripe.elements();
const elements = stripe.elements();

Now you can use Elements to create payment forms with prebuilt input fields to collect payment method details. See accept a payment for detailed instructions.

npm umd

Install React Stripe.js and the Stripe.js loader from the npm public registry.

Terminal
npm install --save @stripe/react-stripe-js @stripe/stripe-js
npm install --save @stripe/react-stripe-js @stripe/stripe-js

We also provide a UMD build for sites that do not use npm or modules.

Include the Stripe.js script, which exports a global Stripe function, and the UMD build of React Stripe.js, which exports a global ReactStripe object. Always load the Stripe.js script directly from js.stripe.com to remain PCI compliant. Do not include the script in a bundle or host a copy of it yourself.

<!-- Stripe.js --> <script src="https://js.stripe.com/v3/"></script> <!-- React Stripe.js development build --> <script src="https://unpkg.com/@stripe/react-stripe-js@latest/dist/react-stripe.umd.js"></script> <!-- When you are ready to deploy your site to production, remove the above development script, and include the following production build. --> <script src="https://unpkg.com/@stripe/react-stripe-js@latest/dist/react-stripe.umd.min.js"></script>
<!-- Stripe.js --> <script src="https://js.stripe.com/v3/"></script> <!-- React Stripe.js development build --> <script src="https://unpkg.com/@stripe/react-stripe-js@latest/dist/react-stripe.umd.js"></script> <!-- When you are ready to deploy your site to production, remove the above development script, and include the following production build. --> <script src="https://unpkg.com/@stripe/react-stripe-js@latest/dist/react-stripe.umd.min.js"></script>

The demo in CodeSandbox lets you try out React Stripe.js without having to create a new project.

Add Stripe.js and Elements to your page

To use Element components, wrap the root of your React app in an Elements provider. Call loadStripe with your publishable key and pass the returned Promise to the Elements provider.

index.js
import React from 'react'; import ReactDOM from 'react-dom'; import {Elements} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; import CheckoutForm from './CheckoutForm'; // Make sure to call `loadStripe` outside of a component’s render to avoid // recreating the `Stripe` object on every render. const stripePromise = loadStripe("pk_test_TYooMQauvdEDq54NiTphI7jx"); function App() { return ( <Elements stripe={stripePromise}> <CheckoutForm /> </Elements> ); }; ReactDOM.render(<App />, document.getElementById('root'));
import React from 'react'; import ReactDOM from 'react-dom'; import {Elements} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; import CheckoutForm from './CheckoutForm'; // Make sure to call `loadStripe` outside of a component’s render to avoid // recreating the `Stripe` object on every render. const stripePromise = loadStripe("pk_test_TYooMQauvdEDq54NiTphI7jx"); function App() { return ( <Elements stripe={stripePromise}> <CheckoutForm /> </Elements> ); }; ReactDOM.render(<App />, document.getElementById('root'));

Now you can use Elements to create payment forms with prebuilt input fields to collect payment method details.

The iOS SDK is open source, fully documented, and compatible with apps supporting iOS 11 or above.

CocoaPods Carthage Dynamic Framework
  1. If you haven't already, install the latest version of CocoaPods.
  2. If you don't have an existing Podfile, run the following command to create one:
    Terminal
    pod init
    pod init
  3. Add this line to your Podfile:
    Podfile
    pod 'Stripe'
    pod 'Stripe'
  4. Run the following command:
    Terminal
    pod install
    pod install
  5. Don't forget to use the .xcworkspace file to open your project in Xcode, instead of the .xcodeproj file, from here on out.
  6. In the future, to update to the latest version of the SDK, just run:
    Terminal
    pod update Stripe
    pod update Stripe
  1. If you haven't already, install the latest version of Carthage.
  2. Add this line to your Cartfile:
    Cartfile
    github "stripe/stripe-ios"
    github "stripe/stripe-ios"
  3. Follow the Carthage installation instructions.
  4. In the future, to update to the latest version of the SDK, run the following command:
    Terminal
    carthage update stripe-ios --platform ios
    carthage update stripe-ios --platform ios
  1. Head to our GitHub releases page and download and unzip Stripe.framework.zip.
  2. Drag Stripe.framework to the "Embedded Binaries" section of your Xcode project's "General" settings. Make sure to select "Copy items if needed".
  3. Head to the "Build Phases" section of your Xcode project settings, and create a new "Run Script Build Phase". Paste the following snippet into the text field:
    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Stripe.framework/integrate-dynamic-framework.sh"
    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Stripe.framework/integrate-dynamic-framework.sh"
  4. In the future, to update to the latest version of our SDK, just repeat steps 1 and 2.

For details on the latest SDK release and past versions, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.

When your app starts, configure the SDK with your Stripe publishable key so that it can make requests to the Stripe API.

Swift Objective-C
AppDelegate.swift
import UIKit import Stripe @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { StripeAPI.defaultPublishableKey = "pk_test_TYooMQauvdEDq54NiTphI7jx" // do any other necessary launch configuration return true } }
import UIKit import Stripe @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { StripeAPI.defaultPublishableKey = "pk_test_TYooMQauvdEDq54NiTphI7jx" // do any other necessary launch configuration return true } }
AppDelegate.m
#import "AppDelegate.h" @import Stripe; @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [StripeAPI setDefaultPublishableKey:@"pk_test_TYooMQauvdEDq54NiTphI7jx"]; // do any other necessary launch configuration return YES; } @end
#import "AppDelegate.h" @import Stripe; @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [StripeAPI setDefaultPublishableKey:@"pk_test_TYooMQauvdEDq54NiTphI7jx"]; // do any other necessary launch configuration return YES; } @end

Use your test mode keys while you test and develop, and your live mode keys before you publish your app.

The Android SDK is open source and fully documented.

To install the SDK, add stripe-android to the dependencies block of your app/build.gradle file:

build.gradle
apply plugin: 'com.android.application' android { ... } dependencies { // ... // Stripe Android SDK implementation 'com.stripe:stripe-android:16.1.1' }
apply plugin: 'com.android.application' android { ... } dependencies { // ... // Stripe Android SDK implementation 'com.stripe:stripe-android:16.1.1' }

For details on the latest SDK release and past versions, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.

Configure the SDK with your Stripe publishable key so that it can make requests to the Stripe API, such as in your Application subclass:

Kotlin Java
import com.stripe.android.PaymentConfiguration class MyApp : Application() { override fun onCreate() { super.onCreate() PaymentConfiguration.init( applicationContext, "pk_test_TYooMQauvdEDq54NiTphI7jx" ) } }
import com.stripe.android.PaymentConfiguration class MyApp : Application() { override fun onCreate() { super.onCreate() PaymentConfiguration.init( applicationContext, "pk_test_TYooMQauvdEDq54NiTphI7jx" ) } }
import com.stripe.android.PaymentConfiguration; public class MyApp extends Application { @Override public void onCreate() { super.onCreate(); PaymentConfiguration.init( getApplicationContext(), "pk_test_TYooMQauvdEDq54NiTphI7jx" ); } }
import com.stripe.android.PaymentConfiguration; public class MyApp extends Application { @Override public void onCreate() { super.onCreate(); PaymentConfiguration.init( getApplicationContext(), "pk_test_TYooMQauvdEDq54NiTphI7jx" ); } }

Use your test mode keys while you test and develop, and your live mode keys before you publish your app.

Server-side libraries

Ruby Python PHP Java Node Go .NET

Terminal

# Available as a gem gem install stripe
# Available as a gem gem install stripe

Gemfile

# If you use bundler, you can add this line to your Gemfile gem 'stripe'
# If you use bundler, you can add this line to your Gemfile gem 'stripe'

For more details, check out the API reference or see the source code on GitHub.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests use your account API settings, unless you override the API version. The changelog lists every available version. Note that by default webhook events are structured according to your account API version, unless you set an API version during endpoint creation.

To override the API version, assign the version to the Stripe.api_version property:

require 'stripe' Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' Stripe.api_version = '2020-08-27'
require 'stripe' Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' Stripe.api_version = '2020-08-27'

Or set it per-request:

require 'stripe' intent = Stripe::PaymentIntent.retrieve( 'pi_1DjoWz2eZvKYlo2CHik7nmCx', { stripe_version: '2020-08-27', } ) intent.capture
require 'stripe' intent = Stripe::PaymentIntent.retrieve( 'pi_1DjoWz2eZvKYlo2CHik7nmCx', { stripe_version: '2020-08-27', } ) intent.capture

When overriding it per-request, methods on the returned object reuse the same Stripe version.

You can visit your Dashboard to upgrade your account API version.

Upgrading your server-side library

Minor updates to our libraries are backwards compatible and are generally safe to upgrade to. Major updates often include breaking changes, which may require changes to your code when upgrading. A major version upgrade is sometimes required to use new features.

Major version upgrades may contain breaking changes. When upgrading, carefully review the library changelog, read the relevant migration guide, and test your integration.

Before upgrading your API version in the Dashboard, review both the API changelog and the library changelog.

Update the the version in your Gemfile. You can find the latest library version at the top of the changelog file.

Gemfile

# If you use bundler, you can add this line to your Gemfile gem 'stripe', 'X.XX.X'
# If you use bundler, you can add this line to your Gemfile gem 'stripe', 'X.XX.X'

Terminal

bundle install
bundle install

Terminal

# Install through pip pip install --upgrade stripe
# Install through pip pip install --upgrade stripe

PyPI

# Or find the Stripe package on http://pypi.python.org/pypi/stripe/
# Or find the Stripe package on http://pypi.python.org/pypi/stripe/

requirements.txt

# Find the version you want to pin: # https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md # Specify that version in your requirements.txt file stripe>=2.48.0,<3.0
# Find the version you want to pin: # https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md # Specify that version in your requirements.txt file stripe>=2.48.0,<3.0

For more details, check out the API reference or see the source code on GitHub.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests use your account API settings, unless you override the API version. The changelog lists every available version. Note that by default webhook events are structured according to your account API version, unless you set an API version during endpoint creation.

To override the API version, assign the version to the stripe.api_version property:

import stripe stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" stripe.api_version = "2020-08-27"
import stripe stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" stripe.api_version = "2020-08-27"

Or set it per-request:

import stripe intent = stripe.PaymentIntent.retrieve( "pi_1DjoWz2eZvKYlo2CHik7nmCx", stripe_version="2020-08-27" ) intent.capture()
import stripe intent = stripe.PaymentIntent.retrieve( "pi_1DjoWz2eZvKYlo2CHik7nmCx", stripe_version="2020-08-27" ) intent.capture()

When overriding it per-request, methods on the returned object reuse the same Stripe version.

You can visit your Dashboard to upgrade your account API version.

Upgrading your server-side library

Minor updates to our libraries are backwards compatible and are generally safe to upgrade to. Major updates often include breaking changes, which may require changes to your code when upgrading. A major version upgrade is sometimes required to use new features.

Major version upgrades may contain breaking changes. When upgrading, carefully review the library changelog, read the relevant migration guide, and test your integration.

Before upgrading your API version in the Dashboard, review both the API changelog and the library changelog.

Update the version in your requirements.txt file and run:

Terminal

pip install -r requirements.txt
pip install -r requirements.txt

Terminal

# Install the PHP library via Composer composer require stripe/stripe-php
# Install the PHP library via Composer composer require stripe/stripe-php

Source

# Or download the source directly: https://github.com/stripe/stripe-php/releases
# Or download the source directly: https://github.com/stripe/stripe-php/releases

For more details, check out the API reference or see the source code on GitHub.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests use your account API settings, unless you override the API version. The changelog lists every available version. Note that by default webhook events are structured according to your account API version, unless you set an API version during endpoint creation.

To override the API version, pass the version to the \Stripe\Stripe::setApiVersion() method:

$stripe = new \Stripe\StripeClient([ "api_key" => "sk_test_4eC39HqLyjWDarjtT1zdp7dc", "stripe_version" => "2020-08-27" ]);
$stripe = new \Stripe\StripeClient([ "api_key" => "sk_test_4eC39HqLyjWDarjtT1zdp7dc", "stripe_version" => "2020-08-27" ]);

Or set it per-request:

$intent = $stripe->paymentIntents->capture( 'pi_1DjoWz2eZvKYlo2CHik7nmCx', [], ['stripe_version' => '2020-08-27'] );
$intent = $stripe->paymentIntents->capture( 'pi_1DjoWz2eZvKYlo2CHik7nmCx', [], ['stripe_version' => '2020-08-27'] );

When overriding it per-request, methods on the returned object reuse the same Stripe version.

You can visit your Dashboard to upgrade your account API version.

Upgrading your server-side library

Minor updates to our libraries are backwards compatible and are generally safe to upgrade to. Major updates often include breaking changes, which may require changes to your code when upgrading. A major version upgrade is sometimes required to use new features.

Major version upgrades may contain breaking changes. When upgrading, carefully review the library changelog, read the relevant migration guide, and test your integration.

Before upgrading your API version in the Dashboard, review both the API changelog and the library changelog.

Terminal

composer require stripe/stripe-php
composer require stripe/stripe-php

This will update the the stripe-php library version in your composer.json file.

build.gradle

/* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://mvnrepository.com/artifact/com.stripe/stripe-java or - https://github.com/stripe/stripe-java/releases/latest */ implementation "com.stripe:stripe-java:{VERSION}"
/* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://mvnrepository.com/artifact/com.stripe/stripe-java or - https://github.com/stripe/stripe-java/releases/latest */ implementation "com.stripe:stripe-java:{VERSION}"

pom.xml

<!-- For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://mvnrepository.com/artifact/com.stripe/stripe-java or - https://github.com/stripe/stripe-java/releases/latest --> <dependency> <groupId>com.stripe</groupId> <artifactId>stripe-java</artifactId> <version>{VERSION}</version> </dependency>
<!-- For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://mvnrepository.com/artifact/com.stripe/stripe-java or - https://github.com/stripe/stripe-java/releases/latest --> <dependency> <groupId>com.stripe</groupId> <artifactId>stripe-java</artifactId> <version>{VERSION}</version> </dependency>

Other environments

# For other environments, manually install the following JARs: # - The Stripe JAR from https://github.com/stripe/stripe-java/releases/latest # - Google Gson from https://github.com/google/gson
# For other environments, manually install the following JARs: # - The Stripe JAR from https://github.com/stripe/stripe-java/releases/latest # - Google Gson from https://github.com/google/gson

For more details, check out the API reference or see the source code on GitHub.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests use your account API settings, unless you override the API version. The changelog lists every available version. Note that by default webhook events are structured according to your account API version, unless you set an API version during endpoint creation.

Since Java is strongly typed, the version is fixed in the library. Revert to an older version of the library to change the API version used, and create a webhook endpoint with the same API version as Stripe.API_VERSION property in the library. See our stripe-java changelog for the API version required.

You can visit your Dashboard to upgrade your account API version.

Upgrading your server-side library

Minor updates to our libraries are backwards compatible and are generally safe to upgrade to. Major updates often include breaking changes, which may require changes to your code when upgrading. A major version upgrade is sometimes required to use new features.

Major version upgrades may contain breaking changes. When upgrading, carefully review the library changelog, read the relevant migration guide, and test your integration.

Upgrading your webhook handlers

During the upgrade process, you should create and maintain two webhook endpoints with two different API versions: one for your existing API version, and one for the API version that you want to upgrade to. This allows you to test your new code while maintaining the ability to safely roll back to your existing version if needed.

  • Write your new event handling code using the version of the library you want to upgrade to. When handling incoming events, store the raw body of the request from Stripe in a queue that is processed sequentially
  • Create a new webhook endpoint with the API version you’re upgrading to and point it at your new code.
curl Java Go .NET
curl https://api.stripe.com/v1/webhook_endpoints \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d url="https://example.com/my/webhook/endpoint" \ -d "enabled_events[]"="payment_intent.succeeded" \ -d "enabled_events[]"="payment_intent.payment_failed" \ -d api_version=2020-03-02
curl https://api.stripe.com/v1/webhook_endpoints \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d url="https://example.com/my/webhook/endpoint" \ -d "enabled_events[]"="payment_intent.succeeded" \ -d "enabled_events[]"="payment_intent.payment_failed" \ -d api_version=2020-03-02
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; WebhookEndpointCreateParams params = WebhookEndpointCreateParams.builder() .setUrl("https://example.com/my/webhook/endpoint") .addAllEnabledEvent(Arrays.asList( WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__PAYMENT_FAILED, WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__SUCCEEDED)) .setApiVersion(WebhookEndpointCreateParams.ApiVersion.VERSION_2019_03_14) .build(); WebhookEndpoint.create(params);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; WebhookEndpointCreateParams params = WebhookEndpointCreateParams.builder() .setUrl("https://example.com/my/webhook/endpoint") .addAllEnabledEvent(Arrays.asList( WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__PAYMENT_FAILED, WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__SUCCEEDED)) .setApiVersion(WebhookEndpointCreateParams.ApiVersion.VERSION_2019_03_14) .build(); WebhookEndpoint.create(params);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" params := &stripe.WebhookEndpointParams{ URL: stripe.String("https://example.com/my/webhook/endpoint"), EnabledEvents: stripe.StringSlice([]string{ "payment_intent.succeeded", "payment_intent.payment_failed", }), APIVersion: stripe.String("2020-03-02"), } we, err := webhookendpoint.New(params)
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" params := &stripe.WebhookEndpointParams{ URL: stripe.String("https://example.com/my/webhook/endpoint"), EnabledEvents: stripe.StringSlice([]string{ "payment_intent.succeeded", "payment_intent.payment_failed", }), APIVersion: stripe.String("2020-03-02"), } we, err := webhookendpoint.New(params)
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var options = new WebhookEndpointCreateOptions { Url = "https://example.com/my/webhook/endpoint", EnabledEvents = new List<String> { "payment_intent.succeeded", "payment_intent.payment_failed", }, ApiVersion = "2020-03-02", }; var service = new WebhookEndpointService(); var webhookEndpoint = service.Create(options);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var options = new WebhookEndpointCreateOptions { Url = "https://example.com/my/webhook/endpoint", EnabledEvents = new List<String> { "payment_intent.succeeded", "payment_intent.payment_failed", }, ApiVersion = "2020-03-02", }; var service = new WebhookEndpointService(); var webhookEndpoint = service.Create(options);
  • Test your new event handling code.
  • When you’re confident your new code works as intended, you can start processing events with your new code and disable or delete your old webhook endpoint.

During the upgrade process, make sure you don’t have separate code processing the same events twice. You should have a process or mechanism for switching live event processing between your old code and your new code.

If you’re not using an event queue, you can modify your old code to stop processing events and respond with a 400 HTTP status code. Then, if the new code isn’t working as expected and you need to revert to the old code, you can turn the event processing logic back on and have it respond normally again. As long as you do so within the three day window, you’ll get all the events retried, and not miss any.

Terminal

# Install via npm npm install --save stripe
# Install via npm npm install --save stripe

Usage with TypeScript

Import Stripe as a default import and instantiate it as new Stripe() with the latest API version.

server.ts

import Stripe from 'stripe'; const stripe = new Stripe('sk_test_4eC39HqLyjWDarjtT1zdp7dc', { apiVersion: '2020-08-27', });
import Stripe from 'stripe'; const stripe = new Stripe('sk_test_4eC39HqLyjWDarjtT1zdp7dc', { apiVersion: '2020-08-27', });

For more details, check out the API reference or see the source code on GitHub.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests use your account API settings, unless you override the API version. The changelog lists every available version. Note that by default webhook events are structured according to your account API version, unless you set an API version during endpoint creation.

To override the API version, provide the apiVersion option:

const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc', { apiVersion: '2020-08-27', });
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc', { apiVersion: '2020-08-27', });

Or set it per-request:

const intent = await stripe.paymentIntents.retrieve('pi_1DjoWz2eZvKYlo2CHik7nmCx', { apiVersion: '2020-08-27', });
const intent = await stripe.paymentIntents.retrieve('pi_1DjoWz2eZvKYlo2CHik7nmCx', { apiVersion: '2020-08-27', });

You can visit your Dashboard to upgrade your account API version.

Upgrading your server-side library

Minor updates to our libraries are backwards compatible and are generally safe to upgrade to. Major updates often include breaking changes, which may require changes to your code when upgrading. A major version upgrade is sometimes required to use new features.

Major version upgrades may contain breaking changes. When upgrading, carefully review the library changelog, read the relevant migration guide, and test your integration.

Before upgrading your API version in the Dashboard, review both the API changelog and the library changelog.

For TypeScript users: stripe-node provides types only for the latest API version at the time of release. This version is encoded in the API_VERSION file.

In your project directory update stripe-node to the latest version:

Terminal

npm install stripe@latest
npm install stripe@latest

Terminal

# Make sure your project is using Go Modules go mod init # Install stripe-go go get -u github.com/stripe/stripe-go/v71
# Make sure your project is using Go Modules go mod init # Install stripe-go go get -u github.com/stripe/stripe-go/v71

app.go

// Then import the package import ( "github.com/stripe/stripe-go/v71" )
// Then import the package import ( "github.com/stripe/stripe-go/v71" )

For more details, check out the API reference or see the source code on GitHub.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests use your account API settings, unless you override the API version. The changelog lists every available version. Note that by default webhook events are structured according to your account API version, unless you set an API version during endpoint creation.

Since Go is strongly typed, the version is fixed in the library. Revert to an older version of the library to change the API version used, and create a webhook endpoint with the same API version as stripe.apiversion property in the library. See our stripe-go changelog for the API version required.

You can visit your Dashboard to upgrade your account API version.

Upgrading your server-side library

Minor updates to our libraries are backwards compatible and are generally safe to upgrade to. Major updates often include breaking changes, which may require changes to your code when upgrading. A major version upgrade is sometimes required to use new features.

Major version upgrades may contain breaking changes. When upgrading, carefully review the library changelog, read the relevant migration guide, and test your integration.

Upgrading your webhook handlers

During the upgrade process, you should create and maintain two webhook endpoints with two different API versions: one for your existing API version, and one for the API version that you want to upgrade to. This allows you to test your new code while maintaining the ability to safely roll back to your existing version if needed.

  • Write your new event handling code using the version of the library you want to upgrade to. When handling incoming events, store the raw body of the request from Stripe in a queue that is processed sequentially
  • Create a new webhook endpoint with the API version you’re upgrading to and point it at your new code.
curl Java Go .NET
curl https://api.stripe.com/v1/webhook_endpoints \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d url="https://example.com/my/webhook/endpoint" \ -d "enabled_events[]"="payment_intent.succeeded" \ -d "enabled_events[]"="payment_intent.payment_failed" \ -d api_version=2020-03-02
curl https://api.stripe.com/v1/webhook_endpoints \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d url="https://example.com/my/webhook/endpoint" \ -d "enabled_events[]"="payment_intent.succeeded" \ -d "enabled_events[]"="payment_intent.payment_failed" \ -d api_version=2020-03-02
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; WebhookEndpointCreateParams params = WebhookEndpointCreateParams.builder() .setUrl("https://example.com/my/webhook/endpoint") .addAllEnabledEvent(Arrays.asList( WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__PAYMENT_FAILED, WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__SUCCEEDED)) .setApiVersion(WebhookEndpointCreateParams.ApiVersion.VERSION_2019_03_14) .build(); WebhookEndpoint.create(params);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; WebhookEndpointCreateParams params = WebhookEndpointCreateParams.builder() .setUrl("https://example.com/my/webhook/endpoint") .addAllEnabledEvent(Arrays.asList( WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__PAYMENT_FAILED, WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__SUCCEEDED)) .setApiVersion(WebhookEndpointCreateParams.ApiVersion.VERSION_2019_03_14) .build(); WebhookEndpoint.create(params);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" params := &stripe.WebhookEndpointParams{ URL: stripe.String("https://example.com/my/webhook/endpoint"), EnabledEvents: stripe.StringSlice([]string{ "payment_intent.succeeded", "payment_intent.payment_failed", }), APIVersion: stripe.String("2020-03-02"), } we, err := webhookendpoint.New(params)
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" params := &stripe.WebhookEndpointParams{ URL: stripe.String("https://example.com/my/webhook/endpoint"), EnabledEvents: stripe.StringSlice([]string{ "payment_intent.succeeded", "payment_intent.payment_failed", }), APIVersion: stripe.String("2020-03-02"), } we, err := webhookendpoint.New(params)
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var options = new WebhookEndpointCreateOptions { Url = "https://example.com/my/webhook/endpoint", EnabledEvents = new List<String> { "payment_intent.succeeded", "payment_intent.payment_failed", }, ApiVersion = "2020-03-02", }; var service = new WebhookEndpointService(); var webhookEndpoint = service.Create(options);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var options = new WebhookEndpointCreateOptions { Url = "https://example.com/my/webhook/endpoint", EnabledEvents = new List<String> { "payment_intent.succeeded", "payment_intent.payment_failed", }, ApiVersion = "2020-03-02", }; var service = new WebhookEndpointService(); var webhookEndpoint = service.Create(options);
  • Test your new event handling code.
  • When you’re confident your new code works as intended, you can start processing events with your new code and disable or delete your old webhook endpoint.

During the upgrade process, make sure you don’t have separate code processing the same events twice. You should have a process or mechanism for switching live event processing between your old code and your new code.

If you’re not using an event queue, you can modify your old code to stop processing events and respond with a 400 HTTP status code. Then, if the new code isn’t working as expected and you need to revert to the old code, you can turn the event processing logic back on and have it respond normally again. As long as you do so within the three day window, you’ll get all the events retried, and not miss any.

Terminal

# Install via dotnet dotnet add package Stripe.net dotnet restore
# Install via dotnet dotnet add package Stripe.net dotnet restore

Terminal

# Or install via NuGet PM> Install-Package Stripe.net
# Or install via NuGet PM> Install-Package Stripe.net

For more details, check out the API reference or see the source code on GitHub.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests use your account API settings, unless you override the API version. The changelog lists every available version. Note that by default webhook events are structured according to your account API version, unless you set an API version during endpoint creation.

Since C# is strongly typed, the version is fixed in the library. Revert to an older version of the library to change the API version used, and create a webhook endpoint with the same API version as StripeConfiguration.ApiVersion property in the library. See our stripe-dotnet changelog for the API version required.

You can visit your Dashboard to upgrade your account API version.

Upgrading your server-side library

Minor updates to our libraries are backwards compatible and are generally safe to upgrade to. Major updates often include breaking changes, which may require changes to your code when upgrading. A major version upgrade is sometimes required to use new features.

Major version upgrades may contain breaking changes. When upgrading, carefully review the library changelog, read the relevant migration guide, and test your integration.

Upgrading your webhook handlers

During the upgrade process, you should create and maintain two webhook endpoints with two different API versions: one for your existing API version, and one for the API version that you want to upgrade to. This allows you to test your new code while maintaining the ability to safely roll back to your existing version if needed.

  • Write your new event handling code using the version of the library you want to upgrade to. When handling incoming events, store the raw body of the request from Stripe in a queue that is processed sequentially
  • Create a new webhook endpoint with the API version you’re upgrading to and point it at your new code.
curl Java Go .NET
curl https://api.stripe.com/v1/webhook_endpoints \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d url="https://example.com/my/webhook/endpoint" \ -d "enabled_events[]"="payment_intent.succeeded" \ -d "enabled_events[]"="payment_intent.payment_failed" \ -d api_version=2020-03-02
curl https://api.stripe.com/v1/webhook_endpoints \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d url="https://example.com/my/webhook/endpoint" \ -d "enabled_events[]"="payment_intent.succeeded" \ -d "enabled_events[]"="payment_intent.payment_failed" \ -d api_version=2020-03-02
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; WebhookEndpointCreateParams params = WebhookEndpointCreateParams.builder() .setUrl("https://example.com/my/webhook/endpoint") .addAllEnabledEvent(Arrays.asList( WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__PAYMENT_FAILED, WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__SUCCEEDED)) .setApiVersion(WebhookEndpointCreateParams.ApiVersion.VERSION_2019_03_14) .build(); WebhookEndpoint.create(params);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; WebhookEndpointCreateParams params = WebhookEndpointCreateParams.builder() .setUrl("https://example.com/my/webhook/endpoint") .addAllEnabledEvent(Arrays.asList( WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__PAYMENT_FAILED, WebhookEndpointCreateParams.EnabledEvent.PAYMENT_INTENT__SUCCEEDED)) .setApiVersion(WebhookEndpointCreateParams.ApiVersion.VERSION_2019_03_14) .build(); WebhookEndpoint.create(params);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" params := &stripe.WebhookEndpointParams{ URL: stripe.String("https://example.com/my/webhook/endpoint"), EnabledEvents: stripe.StringSlice([]string{ "payment_intent.succeeded", "payment_intent.payment_failed", }), APIVersion: stripe.String("2020-03-02"), } we, err := webhookendpoint.New(params)
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" params := &stripe.WebhookEndpointParams{ URL: stripe.String("https://example.com/my/webhook/endpoint"), EnabledEvents: stripe.StringSlice([]string{ "payment_intent.succeeded", "payment_intent.payment_failed", }), APIVersion: stripe.String("2020-03-02"), } we, err := webhookendpoint.New(params)
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var options = new WebhookEndpointCreateOptions { Url = "https://example.com/my/webhook/endpoint", EnabledEvents = new List<String> { "payment_intent.succeeded", "payment_intent.payment_failed", }, ApiVersion = "2020-03-02", }; var service = new WebhookEndpointService(); var webhookEndpoint = service.Create(options);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var options = new WebhookEndpointCreateOptions { Url = "https://example.com/my/webhook/endpoint", EnabledEvents = new List<String> { "payment_intent.succeeded", "payment_intent.payment_failed", }, ApiVersion = "2020-03-02", }; var service = new WebhookEndpointService(); var webhookEndpoint = service.Create(options);
  • Test your new event handling code.
  • When you’re confident your new code works as intended, you can start processing events with your new code and disable or delete your old webhook endpoint.

During the upgrade process, make sure you don’t have separate code processing the same events twice. You should have a process or mechanism for switching live event processing between your old code and your new code.

If you’re not using an event queue, you can modify your old code to stop processing events and respond with a 400 HTTP status code. Then, if the new code isn’t working as expected and you need to revert to the old code, you can turn the event processing logic back on and have it respond normally again. As long as you do so within the three day window, you’ll get all the events retried, and not miss any.

Community libraries

Find some of the many community-supported libraries available for Stripe listed below.

  • Angular

    • Angular-Stripe by Ben Drucker
  • C#

    • ServiceStack.Stripe by TeamServiceStack
  • ColdFusion

    • CFPayment by Brian Ghidinelli
    • ColdFusion-Stripe-CFC by James Eisenlohr
  • Elixir

    • stripe-elixir by Sikan He
    • Stripe for Elixir by Code Corps
    • Stripy by Heresy
  • JavaScript

    • Vue Stripe Elements by fromAtoB
  • Perl

    • Business-Stripe by Paul Pham
    • Stripe Perl by Luke Closs.
  • PHP

    • CakePHP-StripeComponent Plugin by Gregory Gaskill
    • Laravel: Cashier by Laravel
    • PHP-StripeOAuth by Oliver Nassar
    • Stripe by Cartalyst
  • React Native

    • Tipsi-Stripe by Tipsi
  • Ruby

    • ActiveMerchant by Ross Boucher and Greg Brockman
    • Payola, a Rails engine by Pete Keen
    • Spree by Greg Brockman
  • Other

    • Choreos by Temboo
    • GWT by ArcBees
    • Haskell by David Johnson
    • Smalltalk/Seaside by Paul DeBruicker
    • Stripe-CLI by Andy Cohen
    • stripe-clojure by Prachetas Prabhu
    • Stripe Dart by Martin Flucka and Matias Meno at Exit Live.
    • Stripe Elements for Ember.js by Code Corps
    • flutter_stripe_payment by Jonas Bark
Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.