Dodo Payments
Configure the Dodo Payments gateway.
MuseMVP integrates Dodo Payments as one of its payment gateways. Through the unified Muse Billing module, it handles subscriptions, one-time purchases, and the customer portal with the same contract and access model as Creem, Stripe, and Waffo. This guide explains how to configure the Dodo gateway and understand how it works.
Set the default gateway
When Dodo Payments is your primary checkout provider, set BILLING_DEFAULT_GATEWAY=muse_dodo.
Gateway selection
You can still override the gateway per checkout request. The environment default is used by pricing and launch flows.
Get the Dodo API key
Retrieve your API key from the Dodo Payments Dashboard and set DODO_PAYMENTS_API_KEY and DODO_PAYMENTS_ENVIRONMENT.
Key Security
Keep gateway secrets in env files or the platform secret store. Never expose them to the client or version control.
Get the Dodo webhook secret
In the Dodo Payments Dashboard, create a Webhook and set the callback URL to:
https://example.com/api/muse-billing/notify/muse_dodoSelect the event types to listen for (or all):
payment.succeededpayment.failedpayment.processingpayment.cancelledsubscription.activesubscription.updatedsubscription.on_holdsubscription.renewedsubscription.plan_changedsubscription.cancelledsubscription.failedsubscription.expired
Set DODO_PAYMENTS_WEBHOOK_SECRET to the Dodo webhook signing secret.
Key Security
The webhook secret is a server-side environment variable. A mismatch with Dodo will reject every webhook.
Create products and get product IDs
Checkout product IDs are DODO_PRODUCT_ID_PRO_MONTHLY, DODO_PRODUCT_ID_PRO_YEARLY, and DODO_PRODUCT_ID_LIFETIME. The public pricing UI uses stable app plan IDs.
After creating the corresponding products in the Dodo Payments Dashboard, paste the product IDs into the DODO_PRODUCT_ID_* environment variables.
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.
Run
ngrok http 3000Callback domain
Use the terminal domain shown above as the callback URL in your webhook configuration.
Switch to test mode
Set DODO_PAYMENTS_ENVIRONMENT=test_mode and use Dodo test mode in the Dashboard.
Test mode
Payments in Dodo test mode do not result in real charges, making it safe for local testing of subscription and one-time purchase flows.
How it works
Learn how Muse Billing integrates Dodo Payments into the system.
Integration files
| File | Purpose |
|---|---|
dodo/gateway.ts | Dodo gateway implementation: checkout session launch, webhook parsing, customer portal. |
dodo/mappers.ts | Maps Dodo webhook events and subscription states into Muse contract snapshots. |
router.ts | API routes: exposes /api/muse-billing/* endpoints. |
Core workflow
The action flow for payment and accessing the customer portal:
Frontend calls POST /api/muse-billing/launch with productId, optional gatewayId (defaults to orchestrator selection), etc.
Server resolves the Dodo product or price ID from DODO_PRODUCT_ID_* environment variables.
Creates a Dodo checkout session and returns launchUrl for the frontend to redirect to the hosted checkout page.
After payment, Dodo sends a webhook; the server verifies the signature and syncs contract lifecycle and access window 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 Dodo customer portal for managing subscriptions or downloading receipts.
Related docs
- Creem Payment Gateway — Alternative payment gateway
- Stripe Payment Gateway — Alternative payment gateway
- Waffo Pancake Gateway — Alternative payment gateway
- Environment Variables — Gateway credentials and checkout product IDs
- Basic Configuration — Pricing catalog and stable plan IDs