Stripe

Get the Stripe secret key

Retrieve your key from the Stripe Dashboard and set STRIPE_SECRET_KEY.

Get the Stripe webhook secret

Create a webhook: Fill in the callback URL and select event types:

In the Stripe Dashboard, add a Webhook endpoint and set the URL to:

https://example.com/api/muse-billing/notify/muse_stripe

Select the event types to listen for (or all):

• checkout.session.completed
• customer.subscription.*
• invoice.*

Set STRIPE_WEBHOOK_SECRET to the signing secret from the Stripe webhook endpoint.

Create Products and Copy Their Price IDs

Create a monthly recurring price, a yearly recurring price, and a one-time price for the plans you offer. Despite their variable names, fill these mappings with Stripe Price IDs (price_...), not Product IDs (prod_...):

BILLING_DEFAULT_GATEWAY="muse_stripe"
STRIPE_PRODUCT_ID_PRO_MONTHLY="price_your_monthly_price"
STRIPE_PRODUCT_ID_PRO_YEARLY="price_your_yearly_price"
STRIPE_PRODUCT_ID_LIFETIME="price_your_one_time_price"

Only configure plans you enable. Match the currency, amount, and interval shown in your app to the Stripe prices, and use prices from the same test/live mode as your secret key. The public pricing UI keeps stable app plan IDs.

The current gateway uses a stored Stripe Price when the mapped value starts with price_. Other values use inline price_data built from the app order; they do not automatically select a Stripe Product. Use explicit Price IDs for the Dashboard-managed setup in this guide.

Download Ngrok

Ngrok (https://dashboard.ngrok.com/get-started/setup/windows) is a reverse proxy tool that exposes your local development server to the public internet.

Run

ngrok http 3000

Test

Use the test cards above to simulate a production environment locally, covering subscriptions, one-time purchases, payment management, and more.

Frontend calls POST /api/muse-billing/launch with productId, optional gatewayId (defaults to orchestrator selection), etc.

Server resolves the mapped value from STRIPE_PRODUCT_ID_*; price_ values select a Stripe Price, otherwise the gateway builds inline price data from the order.

Creates a Stripe Checkout Session and returns launchUrl for the frontend to redirect to the checkout page.

After payment, Stripe sends a webhook; the server verifies the signature and syncs contract state to the database.

When the user needs to access the platform portal, call POST /api/muse-billing/customer-hub to get a redirect link to the official Stripe Customer Portal for managing subscriptions or downloading receipts.