A fake but stateful Stripe server that you can run locally, for testing purposes.

This is a program that you can launch to simulate a Stripe server locally, without touching real Stripe servers nor the Internet.

Unlike other test/mock software like stripe-mock, localstripe is stateful: it keeps track of the actions performed (creating a customer, adding a card, etc.) so that these actions have an impact on the next queries.

The goal is to have a ready-to-use mock server for end-to-end testing any application.

• works with any language: localstripe is not a library that you include, but a real server that you can query at http://localhost:8420, using regular Stripe API requests
• stateful: if you create a Stripe object (let's say, a customer), you will get it back on future requests
• integrates with Stripe Elements: localstripe includes a JavaScript file that can mock Stripe Elements on any webpage, allowing you to create tokens on the fake server, from your webpage
• supports webhooks that you can customize using a special API route

• no Stripe Connect support: localstripe currently only supports Stripe Payments, and does not support Stripe Connect

Install localstripe:

pip3 install --user -U localstripe
# or, to install globally:
sudo pip3 install localstripe

Then simply run the command localstripe. The fake Stripe server is now listening on port 8420.

Or launch a Docker container:

docker run -p 8420:8420 adrienverge/localstripe:latest

Docker image can be rebuilt using:

docker build -t adrienverge/localstripe -<<EOF
FROM python:3
RUN pip install localstripe
CMD ["localstripe"]
EOF

In the following example, let's create a Plan, a Customer, and subscribe the latter to the former:

curl localhost:8420/v1/plans -u sk_test_12345: \
     -d id=pro-plan \
     -d amount=2500 \
     -d currency=eur \
     -d interval=month \
     -d name="Plan for professionals"

{
  "amount": 2500,
  "created": 1504187388,
  "currency": "eur",
  "id": "pro-plan",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {},
  "name": "Plan for professionals",
  "object": "plan",
  "statement_descriptor": null,
  "trial_period_days": null
}

curl localhost:8420/v1/customers -u sk_test_12345: \
     -d description="Customer for [email protected]"

{
  "id": "cus_b3IecP7GlNCPMM",
  "description": "Customer for [email protected]",
  "account_balance": 0,
  "currency": "eur",
  "default_source": null,
  ...
}

curl localhost:8420/v1/subscriptions -u sk_test_12345: \
     -d customer=cus_b3IecP7GlNCPMM \
     -d items[0][plan]=pro-plan

{
  "id": "sub_UJIdAleo3FnwG7",
  "customer": "cus_b3IecP7GlNCPMM",
  "current_period_end": 1506779564,
  "current_period_start": 1504187564,
  "items": {
  ...
}

Now if you retrieve that customer again, it has an associated subscription:

curl localhost:8420/v1/customers/cus_b3IecP7GlNCPMM -u sk_test_12345:

{
  "id": "cus_b3IecP7GlNCPMM",
  "description": "Customer for [email protected]",
  ...
  "subscriptions": {
    "data": [
      {
        "id": "sub_UJIdAleo3FnwG7",
        "items": {
          "data": [
            {
              "id": "si_2y5q9Q6lvAB9cr",
              "plan": {
                "id": "pro-plan",
                "name": "Plan for professionals",
                "amount": 2500,
                "currency": "eur",
                "interval": "month",
  ...
}

For instance in a Python application, you only need to set stripe.api_base to http://localhost:8420:

import stripe

stripe.api_key = 'sk_test_12345'
stripe.api_base = 'http://localhost:8420'

If your application takes card numbers on a web page using Stripe Elements, you may want tokens to be sent to the mock server inside of the real Stripe server.

To achieve this, you need to load the http://localhost:8420/js.stripe.com/v3/ script into your page. It will overwrite the global Stripe object, so new elements and card forms will actually send data to the http://localhost:8420/v1/tokens API.

For example if you use a testing tool like Protractor, you need to inject this JavaScript source in the web page before it creates card elements:

<script src="http://localhost:8420/js.stripe.com/v3/"></script>

Register a webhook using the special /_config route:

curl localhost:8420/_config/webhooks/mywebhook1 \
     -d url=http://localhost:8888/api/url -d secret=whsec_s3cr3t

Then, localstripe will send webhooks to this url. Only those events types are currently supported:

• Product: product.created
• Plan: plan.created
• Customer: customer.created, customer.updated and customer.deleted
• Source: customer.source.created
• Subscription: customer.subscription.created and customer.subscription.deleted
• Invoice: invoice.created, invoice.payment_succeeded and invoice.payment_failed

To quickly run localstripe from source, and reload when a file changed:

find -name '*.py' | entr -r python3 -m localstripe

To quickly build and run localstripe from source:

python3 setup.py sdist
pip3 install --user --upgrade dist/localstripe-*.tar.gz
localstripe

This program is licensed under the GNU General Public License version 3.