The Stripe API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
You can use the Stripe API in test mode, which doesn’t affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode. Test mode supports some v2 APIs.
The Stripe API doesn’t support bulk updates. You can work on only one object per request.
The Stripe API differs for every account as we release new versions and tailor functionality. Log in to see docs with your test key and data.
Just getting started?
Check out our development quickstart guide.
Not a developer?
Use Stripe’s no-code options or apps from our partners to get started with Stripe and to do more with your Stripe account—no code required.
The Stripe API uses API keys to authenticate requests. You can view and manage your API keys in the Stripe Dashboard.
Test mode secret keys have the prefix sk_ and live mode secret keys have the prefix sk_. 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.
A sample test API key is included in all the examples here, so you can test any example right away. Do not submit any personally identifiable information in requests made with this key.
To test requests using your account, replace the sample API key with your actual API key or sign in.
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 number and 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 payment_ on a charge expands the payment_ property into a full PaymentIntent object, then expands the customer property on that payment intent into a full Customer 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. 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 data.).
You can expand multiple objects at the same time by identifying multiple items in the expand array.
- Related guide: Expanding responses
- Related video: Expand
{ "id": "ch_3LmzzQ2eZvKYlo2C0XjzUzJV", "object": "charge", "customer": { "id": "cu_14HOpH2eZvKYlo2CxXIM7Pb2", "object": "customer", // ... }, "payment_intent": { "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa", "object": "payment_intent", "customer": { "id": "cus_NffrFeUfNV2Hib", "object": "customer", // ... }, // ... }, // ...}