Stripe API Reference (original) (raw)

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.

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.

Client Libraries

By default, the Stripe API Docs demonstrate using curl to interact with the API over HTTP. Select one of our official client libraries to see examples in code.

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.

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


curl https://api.stripe.com/v1/charges \

  -u sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:

# The colon prevents curl from asking for a password.

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.


curl https://api.stripe.com/v1/charges/ch_3LmjFA2eZvKYlo2C09TLIsrw \

  -u sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2: \

  -H "Stripe-Account: acct_1032D82eZvKYlo2C" \

  -G

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

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

decline_codenullable string

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

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 object
The PaymentIntent object for errors returned on a request involving a PaymentIntent.

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

More

advice_codenullable string

network_advice_codenullable string

network_decline_codenullable string

payment_methodnullable object

payment_method_typenullable string

request_log_urlnullable string

setup_intentnullable object

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.


# Select a client library to see examples of

# handling different kinds of errors.