Waffo Payments

Get the Merchant ID and test private key

1. Sign in to the Waffo Pancake Merchant Dashboard
2. Open Integration and select Test Mode
3. Copy the Merchant ID at the top of the page (MER_xxx)
4. Create a test key under Create API Key, then copy the private key or use Copy .env config
5. Add the credentials to the local server environment:

WAFFO_MERCHANT_ID=MER_xxxxxxxxxxxxxxxxxxxxxxxx
WAFFO_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
WAFFO_ENVIRONMENT=test

Waffo isolates test and production API keys. When switching the Dashboard environment, replace both the private key and WAFFO_ENVIRONMENT; otherwise API requests or Webhook verification will fail.

Keep the PEM format copied from the Dashboard. For a single-line .env value, preserve the quotes and escaped \n line breaks; the Waffo SDK normalizes the PEM value automatically.

Create products in Waffo

EasyStarter defaults to three plans: Free, Pro (monthly + yearly), and Lifetime (one-time purchase). The Free plan does not require a Waffo product.

Open Products in the Merchant Dashboard and create these three products:

After saving each product, copy its Product ID (PROD_xxx). EasyStarter stores Waffo Product IDs in the shared providerPriceId field.

If you offer a trial, configure its duration on the Waffo subscription product or product group and keep the next step's trialDays value in sync.

Configure pricing plans

Add the Waffo Product IDs to web.payments.plans in packages/app-config/src/app-config.ts:

web: {
  payments: {
    provider: "waffo",
    plans: [
      {
        id: "free",
      },
      {
        id: "pro",
        prices: [
          {
            id: "monthly",
            provider: "waffo",
            test: {
              providerPriceId: "PROD_xxxxxxxxxxxxxxxx", // Test monthly Product ID
            },
            prod: {
              providerPriceId: "PROD_xxxxxxxxxxxxxxxx", // Production monthly Product ID
            },
            currency: "usd",
            amountCents: 1000,
            priceType: "subscription",
            interval: "month",
            trialDays: 7,
            status: "active",
          },
          {
            id: "yearly",
            provider: "waffo",
            test: {
              providerPriceId: "PROD_xxxxxxxxxxxxxxxx", // Test yearly Product ID
            },
            prod: {
              providerPriceId: "PROD_xxxxxxxxxxxxxxxx", // Production yearly Product ID
            },
            currency: "usd",
            amountCents: 10000,
            priceType: "subscription",
            interval: "year",
            trialDays: 7,
            status: "active",
          },
        ],
      },
      {
        id: "lifetime",
        prices: [
          {
            id: "lifetime",
            provider: "waffo",
            test: {
              providerPriceId: "PROD_xxxxxxxxxxxxxxxx", // Test one-time Product ID
            },
            prod: {
              providerPriceId: "PROD_xxxxxxxxxxxxxxxx", // Production one-time Product ID
            },
            currency: "usd",
            amountCents: 20000,
            priceType: "lifetime",
            status: "active",
          },
        ],
      },
    ],
  },
},

Field reference:

Waffo product APIs use display amounts such as "10.00". EasyStarter's local catalog still uses cents, so $10.00 is amountCents: 1000.

Configure Waffo Webhooks

Webhooks are required to grant entitlements after checkout and keep subscription state synchronized.

1. Open Settings → Webhooks in the Waffo Merchant Dashboard

2. Add an HTTP Webhook and select the test or production environment that matches the current credentials

3. Set the Endpoint URL:

   • Local development: https://your-ngrok-url/api/webhooks/waffo
   • Production: https://your-server.workers.dev/api/webhooks/waffo

4. Subscribe to the events handled by EasyStarter:

   Event	EasyStarter behavior
   order.completed	Complete a one-time purchase or credit package order
   subscription.activated	Activate the subscription
   subscription.payment_succeeded	Synchronize a successful renewal
   subscription.canceling	Mark cancellation at period end and keep current access
   subscription.uncanceled	Restore a subscription that was scheduled to cancel
   subscription.updated	Synchronize subscription changes
   subscription.canceled	Mark the subscription as terminated
   subscription.past_due	Mark a failed renewal as past due
   refund.succeeded	Revoke the corresponding lifetime or credit entitlement
   refund.failed	Record delivery without changing entitlements

Waffo signs the raw request body with RSA-SHA256 and sends the signature in x-waffo-signature. EasyStarter reads the raw text and verifies it with the Waffo SDK, so no separate Webhook secret is required.

Use ngrok to forward the Server's 3001 port during local development. Avoid tunnel services that strip custom request headers, because losing x-waffo-signature makes verification impossible.

ngrok http 3001

Start the app and complete a sandbox checkout

Start the Web and Server apps:

pnpm dev:web+server

Open the pricing page and complete a test checkout. Waffo checkout opens in a new tab so EasyStarter keeps the current merchant page state.

Use any future expiry date and any CVC. After payment, confirm the Server receives POST /api/webhooks/waffo with a 200 response, then check the subscription or lifetime entitlement at /settings/billing.