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 customized to your version of the API, 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
$gem install stripe

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 Ruby 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
require 'stripe'
Stripe.api_key = 'sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc'
Per-Request API Key
require 'stripe'
charge = Stripe::Charge.retrieve(
'ch_3Ln3cj2eZvKYlo2C1lcnB8f6',
{
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.

Global API Key
require 'stripe'
charge = Stripe::Charge.retrieve(
'ch_3Lmjo22eZvKYlo2C1kuO4yZM',
{
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 hash

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

More

  • chargenullable string

  • payment_method_typenullable string

  • doc_urlnullable string

  • request_log_urlnullable string

  • setup_intentnullable hash

  • sourcenullable hash

  • payment_methodnullable hash

HTTP Status Code Summary
200OKEverything worked as expected.
400Bad RequestThe request was unacceptable, often due to missing a required parameter.
401UnauthorizedNo valid API key provided.
402Request FailedThe parameters were valid but the request failed.
403ForbiddenThe API key doesn’t have permissions to perform the request.
404Not FoundThe requested resource doesn’t exist.
409ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504Server ErrorsSomething went wrong on Stripe’s end. (These are rare.)
Error Types
api_errorAPI errors cover any other type of problem (e.g., a temporary problem with Stripe’s servers), and are extremely uncommon.
card_errorCard 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_errorIdempotency 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_errorInvalid 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.

begin
# Use Stripe's library to make requests...
rescue Stripe::CardError => e
puts "Status is: #{e.http_status}"
puts "Type is: #{e.error.type}"
puts "Charge ID is: #{e.error.charge}"
# The following fields are optional
puts "Code is: #{e.error.code}" if e.error.code
puts "Decline code is: #{e.error.decline_code}" if e.error.decline_code
puts "Param is: #{e.error.param}" if e.error.param
puts "Message is: #{e.error.message}" if e.error.message
rescue Stripe::RateLimitError => e
# Too many requests made to the API too quickly
rescue Stripe::InvalidRequestError => e
# Invalid parameters were supplied to Stripe's API
rescue Stripe::AuthenticationError => e
# Authentication with Stripe's API failed
# (maybe you changed API keys recently)
rescue Stripe::APIConnectionError => e
# Network communication with Stripe failed
rescue Stripe::StripeError => e
# Display a very generic error to the user, and maybe send
# yourself an email
rescue => e
# Something else happened, completely unrelated to Stripe
end
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$