Introduction to server-side SDKs

The Stripe server-side SDKs reduce the amount of work required to use our REST APIs. Stripe-maintained SDKs are available for Ruby, PHP, Java, Python, Node, .NET and Go. Community libraries are also available for other server languages.

Installation and setup

Select your language in the language selector below, then follow the instructions to install the SDK.

After completing the installation, you need to initialize Stripe:

Send API requests

You can manipulate objects with the Stripe API in six primary ways: create, update, delete, retrieve, list, and search. The following examples show each of the six ways using the Customer object:

API requests can contain different types of parameters. For example, here’s how to create a customer with a name (a string), address (an object), and preferred_locales (a list):

When updating an object, you can clear some of its properties. For dynamically typed languages, send an empty string. For strongly typed languages, use specific constants. For example, here’s how to clear the name (a string) and metadata (a hash of key-value pairs) of a customer:

This example clears all metadata, but you can also clear individual keys. Learn more about managing metadata in our metadata guide.

Access the API response

Every time you make an API request, Stripe sends you back a response.

If you create, retrieve, or update an object, you get back the object itself:

Use a variable to access the properties of that object:

When listing or searching for objects, you get back a List object containing a data array with the objects requested:

Use a loop on the data array to access the properties of each object:

You could also use auto-pagination to iterate over all the results.

Expanding responses

Some properties are expandable or includable, meaning you can return them by using the expand parameter. For example:

• Retrieve a PaymentIntent and expand its associated PaymentMethod.
• Retrieve a Checkout Session and include the line_items property.

Learn more about expanding responses.

Retrieve the request ID

Each API request has a unique request ID (req_xxx) associated with it. You can use it to inspect the request in the Dashboard to see the parameters Stripe received, or to share it with Stripe support when you need to resolve an issue.

You can find the IDs in your Dashboard logs, or directly with code like this:

Set additional request options

When sending API requests, you can set additional request options to:

• Set a specific API version.
• Make requests on your connected accounts.
• Provide idempotency keys.

Error handling

Each server SDK interprets error responses from the Stripe API as exception types, so you don’t need to parse the response status yourself. Use error handling conventions appropriate for each language to handle those errors.

Learn more about error handling.

Undocumented params and fields

In some cases, you might encounter parameters on an API request or fields on an API response that aren’t available using the SDKs for strongly typed languages. Use the workarounds in this section to send undocumented parameters or access undocumented fields.

Send undocumented parameters:

Access undocumented fields:

Source code

The source code for each of our server SDKs is available on GitHub:

StripeClient

The StripeClient class acts as an entry point to help you discover resources and make requests to the Stripe API. The benefits of using this pattern over the older one that used global configuration are:

• You can simultaneously use multiple clients with different configuration options (such as API keys).
• It enables easier mocking during testing as StripeClient doesn’t use static methods.
• No extra API calls. In some languages, you had to call a retrieve before doing an update or delete. When using StripeClient, you can access all API endpoints with a single method call.

The Node.js SDK has always had the Stripe class which followed the same pattern. For rest of the languages, the new pattern was added in the following SDK versions. If you’re comparing code targeting older versions of these libraries with older patterns, the calls might look different.

Beta versions

Stripe has features in the public preview phase that you can access through versions of the SDKs with the -beta.X suffix (for example, 15.2.0-beta.2). Learn more about the Public Preview release channel.