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 does not 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.

The Stripe API differs for every account as we release new versions and tailor functionality. Log in to see docs customized to your version of the API, with your test key and data.

Subscribe to Stripe's API announce mailing list for updates.

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_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.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" instead of -u sk_test_4eC39HqLyjWDarjtT1zdp7dc.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Clients can make requests as connected accounts using the special header Stripe-Account which should contain a Stripe account ID (usually starting with the prefix acct_).

See also 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).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

Attributes

• type string

  The type of error returned. One of api_connection_error, api_error, authentication_error, card_error, idempotency_error, invalid_request_error, or rate_limit_error

• code string

  For some errors that could be handled programmatically, a short string indicating the error code reported.

• decline_code string

  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.

• message string

  A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.

• param 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.

• payment_intent hash

  The PaymentIntent object for errors returned on a request involving a PaymentIntent.

  Show child attributes

More attributesExpand all

• charge string

• doc_url string

• payment_method hash

• payment_method_type string preview feature

• setup_intent hash

• source hash

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. Responses can be expanded in two ways.

In many cases, an object contains the ID of a related object in its response properties. For example, a Charge may have an associated Customer ID. Those objects can be expanded inline with the expand request parameter. ID fields that can be expanded into objects are noted in this documentation with theexpandable label.

In some cases, such as the Issuing Card object's number and cvc fields, there are available fields that are not included in responses by default. You can request these fields as an expanded response by using the expand request parameter. Fields that can be included in an expanded response are noted in this documentation with the expandable label.

You can expand recursively by specifying nested fields after a dot (.). For example, requesting invoice.subscription on a charge will expand the invoice property into a full Invoice object, and will then expand the subscription property on that invoice into a full Subscription object.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

Expansions on list requests start with the data property. For example, you would expand data.customers on a request to list charges and associated customers. Many deep expansions on list requests can be slow.

Expansions have a maximum depth of four levels (so for example, when listing charges,data.invoice.subscription.default_source is the deepest allowed).

You can expand multiple objects at once by identifying multiple items in the expand array.

Related Guide: Expanding responses

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a charge does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one charge is created.

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request.

Stripe's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Keys are eligible to be removed from the system automatically after they're at least 24 hours old, and a new request is generated if a key is reused after the original has been pruned. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.

Updateable Stripe objects—including Account, Charge, Customer, PaymentIntent, Refund, Subscription, and Transfer—have a metadata parameter. You can use this parameter to attach key-value data to these Stripe objects.

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on a Stripe Customer object. Metadata is not used by Stripe—for example, not used to authorize or decline a charge—and won't be seen by your users unless you choose to show it to them.

Some of the objects listed above also support a description parameter. You can use the description parameter to annotate a charge—with, for example, a human-readable description like 2 shirts for [email protected]. Unlike metadata, description is a single string, and your users may see it (e.g., in email receipts Stripe sends on your behalf).

Do not store any sensitive information (bank account numbers, card details, etc.) as metadata or in the description parameter.

Sample metadata use cases

• Link IDs

  Attach your system's unique IDs to a Stripe object, for easy lookups. For example, add your order number to a charge, your user ID to a customer or recipient, or a unique receipt number to a transfer.

• Refund papertrails

  Store information about why a refund was created, and by whom.

• Customer details

  Annotate a customer by storing an internal ID for your later use.

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list charges, list customers, and list invoices. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.

Stripe utilizes cursor-based pagination via the starting_after and ending_before parameters. Both parameters take an existing object ID value (see below) and return objects in reverse chronological order. The ending_before parameter returns objects listed before the named object. The starting_after parameter returns objects listed after the named object. These parameters are mutually exclusive -- only one of starting_after orending_before may be used.

Our client libraries offer auto-pagination helpers to easily traverse all pages of a list.

Parameters

• limit optional, default is 10

  A limit on the number of objects to be returned, between 1 and 100.

• starting_after optional

  A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

• ending_before optional

  A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

List Response Format

• object string, value is "list"

  A string describing the object type returned.

• data array

  An array containing the actual response elements, paginated by any request parameters.

• has_more boolean

  Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

• url string

  The URL for accessing this list.

Most of our libraries support auto-pagination. This feature easily handles fetching large lists of resources without having to manually paginate results and perform subsequent requests.

Since curl simply emits raw HTTP requests, it doesn't support auto-pagination.

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

When backwards-incompatible changes are made to the API, a new, dated version is released. The current version is 2020-08-27. 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 set the API version on a specific request, send a Stripe-Version header.

You can visit your Dashboard to upgrade your API version. As a precaution, use API versioning to test a new API version before committing to an upgrade.

Attributes

• id string

  Unique identifier for the object. Used to pass to redirectToCheckout in Stripe.js.

• cancel_url string

  The URL the customer will be directed to if they decide to cancel payment and return to your website.

• client_reference_id string

  A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the Session with your internal systems.

• customer string

  expandable

  The ID of the customer for this Session. For Checkout Sessions in payment or subscription mode, Checkout will create a new customer object based on information provided during the payment flow unless an existing customer was provided when the Session was created.

• customer_email string

  If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once the payment flow is complete, use the customer attribute.

• line_items list expandable

  The line items purchased by the customer.

  This field is not included by default. To include it in the response, expand the line_items field.

  Show child attributes

• metadata hash

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

• mode enum

  The mode of the Checkout Session.

  Possible enum values

  • payment

    Accept one-time payments for cards, iDEAL, and more.

  • setup

    Save payment details to charge your customers later.

  • subscription

    Use Stripe Billing to set up fixed-price subscriptions.

• payment_intent string

  expandable

  The ID of the PaymentIntent for Checkout Sessions in payment mode.

• payment_method_types array containing strings

  A list of the types of payment methods (e.g. card) this Checkout Session is allowed to accept.

• payment_status enum

  The payment status of the Checkout Session, one of paid, unpaid, or no_payment_required. You can use this value to decide when to fulfill your customer’s order.

  Possible enum values

  • paid

    The payment funds are available in your account.

  • unpaid

    The payment funds are not yet available in your account.

  • no_payment_required

    The Checkout Session is in setup mode and doesn’t require a payment at this time.

• success_url string

  The URL the customer will be directed to after the payment or subscription creation is successful.

More attributesExpand all

• object string, value is "checkout.session"

• allow_promotion_codes boolean

• amount_subtotal integer

• amount_total integer

• billing_address_collection enum

• currency currency

• livemode boolean

• locale enum

• setup_intent string

  expandable

• shipping hash

• shipping_address_collection hash

• submit_type enum

• subscription string

  expandable

• total_details hash

Creates a Session object.

Parameters

• cancel_url required

  The URL the customer will be directed to if they decide to cancel payment and return to your website.

• mode required conditionally

  The mode of the Checkout Session. Required when using prices or setup mode. Pass subscription if the Checkout Session includes at least one recurring item.

  Possible enum values

  • payment

    Accept one-time payments for cards, iDEAL, and more.

  • setup

    Save payment details to charge your customers later.

  • subscription

    Use Stripe Billing to set up fixed-price subscriptions.

• payment_method_types required

  A list of the types of payment methods (e.g., card) this Checkout Session can accept.

  Read more about the supported payment methods and their requirements in our payment method details guide.

  If multiple payment methods are passed, Checkout will dynamically reorder them to prioritize the most relevant payment methods based on the customer’s location and other characteristics.

  Possible enum values

  • alipay
  • card
  • ideal
  • fpx
  • bacs_debit
  • bancontact
  • giropay
  • Show 5 more

• success_url required

  The URL to which Stripe should send customers when payment or setup is complete. If you’d like access to the Checkout Session for the successful payment, read more about it in the guide on fulfilling orders.

• client_reference_id optional

  A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems.

• customer optional

  ID of an existing customer, if one exists. The email stored on the customer will be used to prefill the email field on the Checkout page. If the customer changes their email on the Checkout page, the Customer object will be updated with the new email. If blank for Checkout Sessions in payment or subscription mode, Checkout will create a new customer object based on information provided during the payment flow.

• customer_email optional

  If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once a session is complete, use the customer field.

• line_items optional array of hashes

  A list of items the customer is purchasing. Use this parameter to pass one-time or recurring Prices. One-time Prices in subscription mode will be on the initial invoice only.

  There is a maximum of 100 line items, however it is recommended to consolidate line items if there are more than a few dozen.

  Show child parameters

• metadata optional dictionary

  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

More parametersExpand all

• allow_promotion_codes optional

• billing_address_collection optional enum

• discounts optional array of hashes

• locale optional enum

• payment_intent_data optional dictionary

• setup_intent_data optional dictionary

• shipping_address_collection optional dictionary

• submit_type optional enum

• subscription_data optional dictionary

Returns

Returns a Session object.

Retrieves a Session object.

Parameters

• No parameters.

Returns

Returns a Session object.

Returns a list of Checkout Sessions.

Parameters

• payment_intent optional

  Only return the Checkout Session for the PaymentIntent specified.

• subscription optional

  Only return the Checkout Session for the subscription specified.

More parametersExpand all

• ending_before optional

• limit optional

• starting_after optional

Returns

A dictionary with a data property that contains an array of up to limit Checkout Sessions, starting after Checkout Session starting_after. Each entry in the array is a separate Checkout Session object. If no more Checkout Sessions are available, the resulting array will be empty.

When retrieving a Checkout Session, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

ParametersExpand all

• ending_before optional

• limit optional

• starting_after optional

Returns

A dictionary with a data property that contains an array of up to limit Checkout Session line items, starting after Line Item starting_after. Each entry in the array is a separate Line Item object. If no more line items are available, the resulting array will be empty.