Local Stripe

Local Stripe environment #

Stripe can be configured to run in a local environment. This is useful when you don’t have access to the main Stripe account.

Prerequisites #

Start ngrok static proxy.

Steps #

Create a Stripe sandbox #

  • Create a Stripe account.
  • After authenticating, in the top left corner select sandbox to use. (Business Profile → Switch to sandbox → … … Sandbox)

Note: You do not need to “Complete your profile”, just ignore it.

Secret key #

Secret key should be immediately available in the dashboard (Home → API keys → Secret key). Update STRIPE_SECRET_KEY in .env with your value.

The secret key starts with sk_test_.

Setup billing #

Go to Billing → Overview and press “Setup” or “Continue Setup”.

This will show a setup guide. Fill in the parameters in order:

  • Flat rate
  • Shareable payment links

Afterwards, either click “Create a recurring product” at the right bottom of the screen, or go to “Product catalog” in the dashboard on the left.

Create a product or multiple products if you need. Specify these fields:

  • Name: Product name (e.g., “Starter Plan”, “Professional Plan”)
  • More options
    • Metadata
      • max_entities: number (maximum number of entities allowed)
      • max_invoices_per_month: number (maximum invoices per month)
      • public: true
  • Amount: Price per billing period (e.g., $29.00/month)

Pricing table #

Go to Product catalog → Pricing tables → Create pricing table

Select products you want to add. Continue through the flow.

Note: You probably want to enable “Allow customers to change products”

After clicking “Finish”, copy values from the HTML code into .env:

Webhook #

Go into Search → Webhooks → Add destination

  • Select events
    • Select API version you want to test with: 2025-09-30.clover should work.
    • Select events you want to receive. You can technically select all, but currently only “Customer” events are used.
  • Select Webhook endpoint: https://<your-ngrok-domain>/webhook/stripe
  • Specify endpoint URL

After creating the webhook, in the ’…’ button in top right side of the screen, select “Roll Secret”. Put the secret into STRIPE_WEBHOOK_SIGNING_SECRET.

The webhook secret starts with whsec_.

Go into Search → Customer portal

Enable keys #

Run the following commands to restart services with proper keys:

docker compose down bonsapi
docker compose up bonsapi -d

Note: Substitute bonsapi for whatever service you need.

Customer #

Go into Customer → Add customer

Add data you want, it can be as simple as “John Doe”.

Open the customer, in the panel on the right copy the Customer ID (starts with cus_).

To link the organization you want to test with Stripe, you need to update the database to use this Customer ID.

Currently the simplest way would be finding the organisation first. Use tofu-internal-mcp execute_sql:

SELECT * FROM organization;

After you find your organization, update stripe_customer_id. Writes go through tofu-internal-mcp apply_migration (local-dev only), e.g.:

{
  "name": "Link org to Stripe customer",
  "up_sql": "UPDATE organization SET stripe_customer_id = '<your_stripe_id_here>' WHERE id = '<your_org_id_here>';",
  "down_sql": "UPDATE organization SET stripe_customer_id = NULL WHERE id = '<your_org_id_here>';"
}

Alternative: If you don’t care which org, drop the WHERE clause in the up_sql (and set down_sql to restore as appropriate).

mise db-sql also still works as a deprecated human CLI fallback, but prefer tofu-internal-mcp.

Conclusions #

Now you should be able to test your organisation with billing enabled.

Tip: You might also have problems with Redis if the billing was cached beforehand. Try running:

docker compose restart redis