Python library for the Stripe API.
Clone or download
ob-stripe Merge pull request #476 from stripe/ob-file-upload-stripe-mock
Use stripe-mock for FileUpload tests
Latest commit 4dd5a16 Sep 17, 2018

Stripe Python Library

Build Status Coverage Status

The Stripe Python library provides convenient access to the Stripe API from applications written in the Python language. It includes a pre-defined set of classes for API resources that initialize themselves dynamically from API responses which makes it compatible with a wide range of versions of the Stripe API.


See the Python API docs.


You don't need this source code unless you want to modify the package. If you just want to use the package, just run:

pip install --upgrade stripe

Install from source with:

python install


  • Python 2.7+ or Python 3.4+ (PyPy supported)


The library needs to be configured with your account's secret key which is available in your Stripe Dashboard. Set stripe.api_key to its value:

import stripe
stripe.api_key = "sk_test_..."

# list charges

# retrieve single charge

Per-request Configuration

For apps that need to use multiple keys during the lifetime of a process, like one that uses Stripe Connect, it's also possible to set a per-request key and/or account:

import stripe

# list charges

# retrieve single charge

Configuring a Client

The library can be configured to use urlfetch, requests, pycurl, or urllib2 with stripe.default_http_client:

client = stripe.http_client.UrlFetchClient()
client = stripe.http_client.RequestsClient()
client = stripe.http_client.PycurlClient()
client = stripe.http_client.Urllib2Client()
stripe.default_http_client = client

Without a configured client, by default the library will attempt to load libraries in the order above (i.e. urlfetch is preferred with urllib2 used as a last resort). We usually recommend that people use requests.

Configuring a Proxy

A proxy can be configured with stripe.proxy:

stripe.proxy = ""

Configuring Automatic Retries

Number of automatic retries on requests that fail due to an intermittent network problem can be configured:

stripe.max_network_retries = 2

Idempotency keys are automatically generated and added to requests, when not given, to guarantee that retries are safe.


The library can be configured to emit logging that will give you better insight into what it's doing. The info logging level is usually most appropriate for production use, but debug is also available for more verbosity.

There are a few options for enabling it:

  1. Set the environment variable STRIPE_LOG to the value debug or info

    $ export STRIPE_LOG=debug
  2. Set stripe.log:

    import stripe
    stripe.log = 'debug'
  3. Enable it through Python's logging module:

    import logging

Writing a Plugin

If you're writing a plugin that uses the library, we'd appreciate it if you identified using stripe.set_app_info():

stripe.set_app_info("MyAwesomePlugin", version="1.2.34", url="")

This information is passed along when the library makes calls to the Stripe API.


The test suite depends on stripe-mock, so make sure to fetch and run it from a background terminal (stripe-mock's README also contains instructions for installing via Homebrew and other methods):

go get -u

Install pipenv, then install all dependencies for the project:

pipenv install --dev

Run all tests on all supported Python versions:

make test

Run all tests for a specific Python version (modify -e according to your Python target):

pipenv run tox -e py27

Run all tests in a single file:

pipenv run tox -e py27 -- tests/api_resources/abstract/

Run a single test suite:

pipenv run tox -e py27 -- tests/api_resources/abstract/

Run a single test:

pipenv run tox -e py27 -- tests/api_resources/abstract/

Run the linter with:

make lint