Waffo Pancake

TanStarter uses Waffo Pancake for payment processing, supporting both one-time payments and subscriptions. Waffo Pancake is a Merchant of Record (MoR): it acts as the legal seller and handles global tax calculation, collection, compliance, and payouts on your behalf.

The integration uses the official @waffo/pancake-ts SDK with Waffo's hosted checkout and consumer portal, so no card data ever touches your server.

Setup

TanStarter template provides three pricing plans by default: a free plan, a pro subscription plan (monthly/yearly), and a lifetime plan (one-time payment). Follow these steps to set up:

WAFFO_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEv...\n-----END PRIVATE KEY-----"

# Payment provider
VITE_PAYMENT_PROVIDER=waffo

# Waffo API credentials (server-side only)
WAFFO_MERCHANT_ID=MER_...
WAFFO_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEv...\n-----END PRIVATE KEY-----"

# Optional: accept test-mode webhooks in a production build (smoke testing only)
# WAFFO_DEBUG=true

# Product IDs
VITE_WAFFO_PRODUCT_PRO_MONTHLY=PROD_...
VITE_WAFFO_PRODUCT_PRO_YEARLY=PROD_...
VITE_WAFFO_PRODUCT_LIFETIME=PROD_...

payment: {
  enable: isPaymentEnabled,              // ← auto: true when VITE_PAYMENT_PROVIDER is set
  provider: isPaymentEnabled ? paymentProvider : undefined, // ← auto: 'waffo'
  price: {
    plans: {
      free: {
        id: 'free',
        prices: [],
        isFree: true,
        isLifetime: false,
      },
      pro: {
        id: 'pro',
        prices: [
          {
            type: 'subscription',
            priceId: priceIds.proMonthly,  // ← auto: from VITE_WAFFO_PRODUCT_PRO_MONTHLY
            amount: 990,                   // amount in cents ($9.90)
            currency: 'USD',
            interval: 'month',
          },
          {
            type: 'subscription',
            priceId: priceIds.proYearly,   // ← auto: from VITE_WAFFO_PRODUCT_PRO_YEARLY
            amount: 9900,                  // amount in cents ($99.00)
            currency: 'USD',
            interval: 'year',
          },
        ],
        isFree: false,
        isLifetime: false,
        popular: true,
      },
      lifetime: {
        id: 'lifetime',
        prices: [
          {
            type: 'one_time',
            priceId: priceIds.lifetime,     // ← auto: from VITE_WAFFO_PRODUCT_LIFETIME
            amount: 19900,                  // amount in cents ($199.00)
            currency: 'USD',
            allowPromotionCode: true,
          },
        ],
        isFree: false,
        isLifetime: true,
      },
    },
  },
},

Core Features

• One-time payment for lifetime membership
• Recurring subscription payments (monthly/yearly)
• Free trial period support
• Hosted checkout with buyer attribution (authenticated checkout)
• Webhook handling for payment, subscription, and refund events
• Tax, compliance, and payouts handled by Waffo
• Consumer portal with Magic Link login
• Built-in pricing components (table, card, button)
• Server-side actions for secure payment operations
• Multiple pricing plan support (free, pro, lifetime)

Development

For local development, expose your server with an HTTPS tunnel so Waffo can reach your webhook endpoint. The official docs recommend ngrok; cloudflared also works. Do not use localtunnel — it strips custom HTTP headers such as X-Waffo-Signature:

ngrok http 3000
# or
cloudflared tunnel --url http://localhost:3000

Then:

1. Set the tunnel URL (e.g. https://xxxx.ngrok-free.app/api/webhooks/waffo) as the test webhook URL in Waffo Dashboard > Settings > Webhooks. Never put a temporary tunnel URL into the production webhook.
2. Make a test purchase on the website and verify the event flow works as expected.

The template also ships a Waffo sandbox E2E suite:

pnpm e2e:waffo

Production

1. Complete the store review / KYB so production payments are enabled — see Account Reviews
2. Publish your subscription and one-time products from test to production. Publishing is a one-way, first-publish-only operation — see Publish Product
3. Create a production API key and use it for WAFFO_MERCHANT_ID / WAFFO_PRIVATE_KEY
4. Add the production webhook URL https://YOUR-DOMAIN.com/api/webhooks/waffo in Waffo Dashboard > Settings > Webhooks
5. Leave WAFFO_DEBUG unset (or set to false) so test-mode events are rejected in production — a sandbox purchase must never grant real access

Customer Portal

Waffo provides a hosted consumer portal at https://pancake.waffo.ai/consumer/portal/login. Customers log in with the email used for their purchase and a one-time Magic Link — no password required. In the portal they can:

• View active subscriptions, next billing date, and payment history
• Cancel or reactivate subscriptions
• Download PDF invoices and receipts
• Update billing details
• Request refunds

The Billing page (/settings/billing) sends customers to this portal via the "Manage subscription" button. You can find more about the Customer Portal in the Waffo documentation.

Webhook Events

Waffo supports the following webhook events:

Test Cards

To test the Waffo integration, use Waffo's test mode with these test cards:

Any future expiry date and any 3-digit CVC work. You can find more about test mode and test cards in the Waffo documentation.

Best Practices

1. Protect API keys: Never expose WAFFO_PRIVATE_KEY or the Merchant ID in client-side code
2. Validate webhook signatures: Always verify the X-Waffo-Signature header (the SDK's verifyWebhook() does this)
3. Match environments: Use the test or production API key and webhook URL that correspond to the environment you are running
4. Handle errors gracefully: Provide user-friendly error messages when payments fail
5. Test webhooks thoroughly: Complete a full purchase in test mode before going live

References

• Waffo Pancake Documentation
• Waffo Quickstart
• API Key Authentication
• TypeScript SDK
• Checkout Flow
• Webhooks Guide
• API Reference — Webhooks
• Subscriptions Guide
• One-time Payments Guide
• Test Mode
• Customer Portal