API Reference

The Stripe API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.

We send information on new additions and changes to Stripe's API and language libraries to the API announce mailing list. Be sure to subscribe to stay informed.

API libraries

Official libraries for the Stripe API are available in several languages. Community-supported libraries are also available for additional languages.



Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

To use your API key, assign it to Stripe.api_key. The Ruby library will then automatically send this key in each request.

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

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

You can also set a per-request key like in the example below. This is often useful for Connect applications that use multiple API keys during the lifetime of a process.

Authentication is transparently handled for you in subsequent method calls on the returned object.

  :api_key => "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

A sample test API key is included in all the examples on this page, so you can test any example right away. To test requests using your account, replace the sample API key with your actual API key.