Waffo Pancake

MuseMVP integrates Waffo Pancake 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 Dodo Payments. This guide explains how to configure the Waffo gateway and understand how it works.

Official docs

Use the Waffo Pancake API reference while you configure credentials, products, and webhooks.

Set the default gateway

When Waffo Pancake is your primary checkout provider, set the default gateway to muse_waffo in Admin → Runtime settings.

Gateway selection

You can still override the gateway per checkout request. The stored default is used by pricing and launch flows. If no default is stored, Muse Billing falls back in this order: Creem → Stripe → Dodo → Waffo.

Get merchant credentials

Sign in to the Waffo Merchant Dashboard and copy both values from API & Development. Paste them into Admin → Runtime settings:

Merchant ID: top of the page, copy button. Use the merchant ID (MER_xxx), not a store ID (STO_xxx).
API Key: API Keys section → create a key, then paste the PEM private key.
Environment: test or prod.

Waffo is enabled only when both merchant ID and private key are saved.

Key security

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

Configure the webhook URL

Waffo verifies webhooks with the SDK's embedded public keys. No webhook secret is required.

In the Waffo Merchant Dashboard, add an HTTP webhook and set the callback URL to:

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

Subscribe to the event types Muse Billing maps (or all events):

order.completed
subscription.activated
subscription.payment_succeeded
subscription.updated
subscription.canceling
subscription.uncanceled
subscription.past_due
subscription.canceled
refund.succeeded
refund.failed

Signature header

Muse Billing requires x-waffo-signature on every webhook, including local development. Requests without a valid signature are rejected. The adapter reads request.text() (raw body) before verification — do not parse JSON first.

Optional: enable debug in Admin → Runtime settings to accept sandbox (test) webhooks in a production Node build.

Events whose mode does not match the stored Waffo environment are ignored so test events cannot update production contracts.

Create products and get product IDs

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

After creating the corresponding products in the Waffo Dashboard (Products), copy each PROD_xxx ID from the product detail page or URL into the admin product map.

Environment match

The product IDs must belong to the same Waffo environment as the stored gateway environment. A test-mode product ID in prod (or the reverse) returns a product-not-found error on launch.

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 3000

Callback domain

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

Switch to test mode

Ensure the Waffo environment in Admin → Runtime settings is test and complete a payment in the Waffo test environment.

Test card	Expected result
`4576750000000110`	Successful test payment

Test mode

Payments in Waffo test mode do not result in real charges. After a successful checkout, confirm that order.completed (one-time) or subscription.activated / subscription.payment_succeeded (subscription) arrives at /api/muse-billing/notify/muse_waffo.

How it works

Learn how Muse Billing integrates Waffo Pancake into the system.

Integration files

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

src/modules/muse-billing/lib/gateways/waffo/mappers.ts

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

File	Purpose
`waffo/gateway.ts`	Waffo gateway implementation: authenticated checkout launch, webhook verification, customer portal, subscription cancel.
`waffo/mappers.ts`	Maps Waffo webhook events and order 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 Waffo product ID from the stored billing.productMap settings.

Creates a Waffo authenticated checkout session (buyerIdentity = the signed-in user ID) and returns launchUrl for the frontend to redirect to the hosted checkout page. Checkout metadata includes referenceId and planProductId so the webhook can match the pending contract.

After payment, Waffo sends a webhook; the server verifies x-waffo-signature and syncs contract lifecycle and access window to the database. Subscription snapshots use the Waffo order ID (ORD_xxx) as gatewaySubscriptionId.

When the user needs to access the platform portal, call POST /api/muse-billing/customer-hub. Waffo uses a shared consumer portal (https://pancake.waffo.ai/consumer/portal/login) and does not require a merchant customer ID. Override the URL in Admin → Runtime settings if needed.

Discount codes

Waffo checkout has no discount-code field. If the pricing UI collects a discount code, Muse Billing ignores it for muse_waffo launches.

Creem Payment Gateway — Alternative payment gateway
Stripe Payment Gateway — Alternative payment gateway
Dodo Payments Gateway — Alternative payment gateway
Runtime Settings — Gateway credentials, default gateway, and checkout product IDs
Basic Configuration — Pricing catalog and stable plan IDs
Environment Variables — MUSE_SETTINGS_SECRET and other bootstrap env vars

On this page