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:

  • pricing-table-id → NEXT_PUBLIC_STRIPE_PRICING_TABLE_ID
  • publishable-key → NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

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

Copy the portal link. Put it into NEXT_PUBLIC_STRIPE_CUSTOMER_PORTAL_BASE_URL in .env.

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:

mise db-sql "SELECT * FROM organization;"

After you find your organization, update stripe_customer_id:

mise db-sql "UPDATE organization SET stripe_customer_id = '<your_stripe_id_here>' WHERE id = '<your_org_id_here>';"

Alternative: If you don’t care, you can run this command without searching for organization:

mise db-sql "UPDATE organization SET stripe_customer_id = '<your_id_here>';"

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