https://github.com/adrum/localstripe
A fake but stateful Stripe server that you can run locally, for testing purposes.
https://github.com/adrum/localstripe
Last synced: 5 months ago
JSON representation
A fake but stateful Stripe server that you can run locally, for testing purposes.
- Host: GitHub
- URL: https://github.com/adrum/localstripe
- Owner: adrum
- License: gpl-3.0
- Created: 2025-08-19T01:42:10.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-01-02T04:09:17.000Z (6 months ago)
- Last Synced: 2026-01-07T07:21:27.925Z (5 months ago)
- Language: Python
- Homepage:
- Size: 871 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
Awesome Lists containing this project
README
localstripe
===========
This project is a derivative of https://github.com/adrienverge/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
- **has a UI** to manage the state of the server
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
-----------
Launch a container using `the Docker image
`_:
.. code:: yaml
services:
localstripe:
image: ghcr.io/adrum/localstripe:latest
ports:
- 8420:8420
restart: always
volumes:
- ./data:/data
Examples
--------
In the following example, let's create a ``Plan``, a ``Customer``, and
subscribe the latter to the former:
.. code:: shell
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"
.. code:: shell
{
"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
}
.. code:: shell
curl localhost:8420/v1/customers -u sk_test_12345: \
-d description="Customer for david.anderson@example.com"
.. code:: shell
{
"id": "cus_b3IecP7GlNCPMM",
"description": "Customer for david.anderson@example.com",
"account_balance": 0,
"currency": "eur",
"default_source": null,
...
}
.. code:: shell
curl localhost:8420/v1/subscriptions -u sk_test_12345: \
-d customer=cus_b3IecP7GlNCPMM \
-d items[0][plan]=pro-plan
.. code:: shell
{
"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:
.. code:: shell
curl localhost:8420/v1/customers/cus_b3IecP7GlNCPMM -u sk_test_12345:
.. code:: shell
{
"id": "cus_b3IecP7GlNCPMM",
"description": "Customer for david.anderson@example.com",
...
"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``:
.. code:: python
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:
.. code:: html
Use webhooks
------------
Register a webhook using the special ``/_config`` route:
.. code:: shell
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:
.. code:: shell
curl -X DELETE localhost:8420/_config/data
Hacking and contributing
------------------------
To quickly run localstripe from source, and reload when a file changed:
.. code:: shell
find -name '*.py' | entr -r python -m localstripe --from-scratch
To quickly build and run localstripe from source:
.. code:: shell
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.