localstripe

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.

Features

• 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

Limitations

• only the latest version of Stripe API is supported (on best effort)
• deprecated properties and features may or may not be supported
• no Stripe Connect support: localstripe currently only supports Stripe Payments, and does not support Stripe Connect

Get started

Install localstripe:

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

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

Or launch a container using the Docker image:

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

Docker image can be rebuilt using:

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

Examples

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",
  ...
}

Integrate with your back-end

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'

Integrate with Stripe Elements

If your application takes card numbers on a web page using Stripe Elements, you may want tokens to be sent to the mock server instead 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>

Use webhooks

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, signed using secret. The events option can be used to filter events to be sent. 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

Flush stored data

Flushing data programmatically can be useful to reset localstripe if your are using it with any test framework.

Flushing stored data can be performed using the /_config/data route with DELETE http method:

curl -X DELETE localhost:8420/_config/data

Hacking and contributing

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

find -name '*.py' | entr -r python -m localstripe --from-scratch

To quickly build and run localstripe from source:

python -m build
pip install --user --upgrade dist/localstripe-*.tar.gz
localstripe

If you plan to open a pull request to improve localstripe, that is so cool! To make reviews smooth you should follow our contributing guidelines.

License

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