Test mode secret keys have the prefix
sk_test_ and live mode secret keys have the prefix
sk_live_. Alternatively, you can use restricted API keys for granular permissions.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
- Related video: Authentication
To act as connected accounts, clients can issue requests using the
Stripe-Account special header. Make sure that this header contains a Stripe account ID, which usually starts with the
The value is set per-request as shown in the adjacent code sample. Methods on the returned object reuse the same account ID.
- Related guide: Making API calls for connected accounts
Stripe uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the
2xx range indicate success. Codes in the
4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the
5xx range indicate an error with Stripe’s servers (these are rare).
The type of error returned. One of
- codenullable string
For some errors that could be handled programmatically, a short string indicating the error code reported.
For card errors resulting from a card issuer decline, a short string indicating the card issuer’s reason for the decline if they provide one.
- messagenullable string
A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.
- paramnullable string
If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field.
The PaymentIntent object for errors returned on a request involving a PaymentIntent.
- chargenullable string
method_ typenullable string
log_ urlnullable string
- sourcenullable object
Our Client libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.
- Related guide: Error Handling
Many objects allow you to request additional information as an expanded response by using the
expand request parameter. This parameter is available on all API requests, and applies to the response of that request only. You can expand responses in two ways.
In many cases, an object contains the ID of a related object in its response properties. For example, a
Charge might have an associated Customer ID. You can expand these objects in line with the expand request parameter. The
expandable label in this documentation indicates ID fields that you can expand into objects.
Some available fields aren’t included in the responses by default, such as the
cvc fields for the Issuing Card object. You can request these fields as an expanded response by using the
expand request parameter.
You can expand recursively by specifying nested fields after a dot (
.). For example, requesting
invoice.subscription on a charge expands the
invoice property into a full Invoice object, then expands the
subscription property on that invoice into a full Subscription object.
You can use the
expand parameter on any endpoint that returns expandable fields, including list, create, and update endpoints.
Expansions on list requests start with the
data property. For example, you can expand
data.customers on a request to list charges and associated customers. Performing deep expansions on numerous list requests might result in slower processing times.
Expansions have a maximum depth of four levels (for example, the deepest expansion allowed when listing charges is
You can expand multiple objects at the same time by identifying multiple items in the