Stripe

MuseMVP integrates Stripe as one of its payment gateways, handling subscriptions, one-time purchases, and customer portal through the unified Muse Billing module. This guide explains how to configure the Stripe gateway and understand how it works.

Get the Stripe secret key

Retrieve your key from the Stripe Dashboard. Paste the secret key into Admin → Runtime settings (/app/admin/settings), not into .env. Stripe

Key Security

Gateway credentials are encrypted in the database. Never expose them to the client or version control.

Get the Stripe webhook secret

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

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.*

Copy the webhook secret into Admin → Runtime settings. After saving, confirm the same secret is still configured on the Stripe side. Stripe

Key Security

The webhook secret is stored encrypted in the database. A mismatch with Stripe will reject every webhook.

Create Products and Get Product IDs

Checkout product IDs are stored in Admin → Runtime settings (billing.productMap). The public pricing UI uses stable app plan IDs (pro_monthly, pro_yearly, lifetime).

Stripe Stripe

Local Development Testing

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.

Ngrok

Run

ngrok http 3000

Ngrok

Callback Domain

Use the terminal domain shown above as the callback URL in your webhook configuration.

Test

Test Card Number	Expected Result
`4242 4242 4242 4242`	Successful payment
`4000 0000 0000 0002`	Card declined
`4000 0000 0000 9995`	Insufficient funds
`4000 0000 0000 0127`	Incorrect CVC
`4000 0000 0000 0069`	Expired card

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

Enable Alipay / WeChat Pay

If your product needs to support Alipay or WeChat Pay, you can enable them in the Stripe Dashboard.

Stripe

How It Works

Learn how Muse Billing integrates Stripe into the system.

Integration Files

src/modules/muse-billing/lib/gateways/muse-stripe-gateway.ts

src/modules/muse-billing/lib/orchestrator.ts

src/backend/api/routes/muse-billing/router.ts

File	Purpose
`muse-stripe-gateway.ts`	Stripe gateway implementation: Checkout Session, Webhook parsing, contract sync.
`orchestrator.ts`	Billing orchestration layer: launch, customer-hub, Webhook dispatch.
`router.ts`	API routes: exposes `/api/muse-billing/*` endpoints.

Core Workflow

The action flow for payment and accessing the Customer Hub:

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

Server resolves the Stripe price ID from the stored billing.productMap settings.

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.

Creem Payment Gateway — Alternative payment gateway
Dodo Payments Gateway — Alternative payment gateway
Waffo Pancake Gateway — Alternative payment gateway
Runtime Settings — Gateway credentials, default gateway, and checkout product IDs
Basic Configuration — Pricing catalog and stable plan IDs

On this page