MuseMVP

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 `MUSE_STRIPE_GATEWAY_SECRET_KEY`

Before deploying or running locally, configure the required secrets.

# Stripe secret key (starts with `sk_`)
MUSE_STRIPE_GATEWAY_SECRET_KEY="sk_test_xxx1"

Retrieve your key: Stripe

Key Security

MUSE_STRIPE_GATEWAY_SECRET_KEY is server-side only; never expose it to the client or version control.

Get `MUSE_STRIPE_GATEWAY_WEBHOOK_SECRET`

# Webhook signing secret (starts with `whsec_`)
MUSE_STRIPE_GATEWAY_WEBHOOK_SECRET="whsec_xxx2"

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

Retrieve the webhook secret: Stripe

Key Security

MUSE_STRIPE_GATEWAY_WEBHOOK_SECRET is server-side only; never expose it to the client or version control.

Create Products and Get Product IDs

Product IDs come from config.payments.productCatalog.*.gatewayProductIds.muse_stripe in src/config/index.ts by default, and can be overridden via environment variables:

# Pro monthly subscription price ID
NEXT_PUBLIC_MUSE_STRIPE_PRICE_PRO_MONTHLY_ID="prod_xxx1"
# Pro yearly subscription price ID
NEXT_PUBLIC_MUSE_STRIPE_PRICE_PRO_YEARLY_ID="prod_xxx2"
# Lifetime one-time price ID
NEXT_PUBLIC_MUSE_STRIPE_PRICE_LIFETIME_ID="prod_xxx3"

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 config.payments.productCatalog mapping.

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
Basic Configuration — Pricing and product ID configuration

Stripe

On this page