API Reference

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.

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.

Base URL

https://api.stripe.com

Client Libraries

$pip install stripe
stripe-python

Authentication

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.

Use your API key by assigning it to stripe.api_key. The Python library will then automatically send this key in each request.

You can also set a per-request key with an option. This is often useful for Connect applications that use multiple API keys during the lifetime of a process. Methods on the returned object reuse the same API key.

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

Global API Key

Server-side language

import stripe
stripe.api_key = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc"

Per-Request API Key

Server-side language

import stripe
charge = stripe.Charge.retrieve(
  "ch_3Ln3e92eZvKYlo2C0eUfv7bi",
  api_key="sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc"
)
charge.capture() # Uses the same API Key.

Your API Key

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.

Connected Accounts

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 acct_ prefix.

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

Per-Request Account

Server-side language

import stripe
charge = stripe.Charge.retrieve(
  "ch_3Lmjoz2eZvKYlo2C1rBER4Dk",
  stripe_account="acct_1032D82eZvKYlo2C"
)
charge.capture() # Uses the same account.

Errors

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

typeenum
The type of error returned. One of api_error, card_error, idempotency_error, or invalid_request_error
Possible enum values
api_error
card_error
idempotency_error
invalid_request_error

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

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

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.

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

chargenullable string

payment_method_typenullable string

doc_urlnullable string

request_log_urlnullable string

setup_intentnullable dictionary

sourcenullable dictionary

payment_methodnullable dictionary

HTTP Status Code Summary

200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
402	Request Failed	The parameters were valid but the request failed.
403	Forbidden	The API key doesn’t have permissions to perform the request.
404	Not Found	The requested resource doesn’t exist.
409	Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504	Server Errors	Something went wrong on Stripe’s end. (These are rare.)

Error Types

`api_error`	API errors cover any other type of problem (e.g., a temporary problem with Stripe’s servers), and are extremely uncommon.
`card_error`	Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can’t be charged for some reason.
`idempotency_error`	Idempotency errors occur when an `Idempotency-Key` is re-used on a request that does not match the first request’s API endpoint and parameters.
`invalid_request_error`	Invalid request errors arise when your request has invalid parameters.

Handling errors

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

Server-side language

try:
  # Use Stripe's library to make requests...
  pass
except stripe.error.CardError as e:
  # Since it's a decline, stripe.error.CardError will be caught
  print('Status is: %s' % e.http_status)
  print('Code is: %s' % e.code)
  # param is '' in this case
  print('Param is: %s' % e.param)
  print('Message is: %s' % e.user_message)
except stripe.error.RateLimitError as e:
  # Too many requests made to the API too quickly
  pass
except stripe.error.InvalidRequestError as e:
  # Invalid parameters were supplied to Stripe's API
  pass
except stripe.error.AuthenticationError as e:
  # Authentication with Stripe's API failed
  # (maybe you changed API keys recently)
  pass
except stripe.error.APIConnectionError as e:
  # Network communication with Stripe failed
  pass
except stripe.error.StripeError as e:
  # Display a very generic error to the user, and maybe send
  # yourself an email
  pass
except Exception as e:
  # Something else happened, completely unrelated to Stripe
  pass

API Reference

Just getting started?

Not a developer?

Authentication

Connected Accounts

Errors

Attributes

typeenum

codenullable string

decline_codenullable string

messagenullable string

paramnullable string

payment_intentnullable dictionary

MoreExpand all

chargenullable string

payment_method_typenullable string

doc_urlnullable string

request_log_urlnullable string

setup_intentnullable dictionary

sourcenullable dictionary

payment_methodnullable dictionary

Handling errors

More