https://github.com/adrienverge/localstripe
A fake but stateful Stripe server that you can run locally, for testing purposes.
https://github.com/adrienverge/localstripe
Last synced: about 2 months ago
JSON representation
A fake but stateful Stripe server that you can run locally, for testing purposes.
- Host: GitHub
- URL: https://github.com/adrienverge/localstripe
- Owner: adrienverge
- License: gpl-3.0
- Created: 2017-08-29T17:14:38.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2025-01-27T10:42:32.000Z (5 months ago)
- Last Synced: 2025-05-02T19:43:03.137Z (2 months ago)
- Language: Python
- Homepage:
- Size: 309 KB
- Stars: 203
- Watchers: 7
- Forks: 58
- Open Issues: 27
-
Metadata Files:
- Readme: README.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
Awesome Lists containing this project
README
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:
.. code:: shell
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
`_:
.. code:: shell
docker run -p 8420:8420 adrienverge/localstripe:latest
Docker image can be rebuilt using:
.. code::
docker build --no-cache -t adrienverge/localstripe -<
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.