Create Checkout Session

✨ Install with AI

Copy this prompt to your AI code editor (Cursor, Copilot, etc.) to create checkout integration:

Add Waffo Pancake checkout to my project using the official TypeScript SDK.

npm install @waffo/pancake-ts

Create a WaffoPancake client with WAFFO_MERCHANT_ID and WAFFO_PRIVATE_KEY.
Use client.checkout.createSession({ productId, currency: "USD" })
to get a checkoutUrl, then redirect the user with res.redirect(checkoutUrl).

For webhooks, use verifyWebhook(rawBody, signature) from the SDK — it has embedded public keys,
no secret needed. Handle events: order.completed, subscription.activated, subscription.canceled.

Read https://waffo.mintlify.app/llms-full.txt for full API reference.

What You’ll Build

A checkout session is a dynamically generated payment page. Instead of sharing a static product link, you can:

Pre-fill customer email
Track orders with custom metadata
Set custom success URLs
Enable trial periods for subscriptions
Tailor language and payment methods to your audience

Prerequisites

Waffo Pancake account
API key (Dashboard → API & Development)
At least one product created

Basic Checkout Session

The simplest checkout session needs a product ID and currency.

Using the TypeScript SDK (Recommended)

npm install @waffo/pancake-ts

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
});

// Redirect the user to the checkout page
res.redirect(session.checkoutUrl);

Using REST API Directly

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Store-Slug: your-store-slug" \
  -H "X-Environment: test" \
  -d '{
    "productId": "your-product-uuid",
    "currency": "USD"
  }'

import requests

response = requests.post(
    'https://api.waffo.ai/v1/actions/checkout/create-session',
    headers={
        'Content-Type': 'application/json',
        'X-Store-Slug': 'your-store-slug',
        'X-Environment': 'test',
    },
    json={
        'productId': 'your-product-uuid',
        'currency': 'USD',
    }
)

checkout_url = response.json()['data']['checkoutUrl']
# Redirect customer to checkout_url

Response:

{
  "data": {
    "sessionId": "cs_xxx",
    "checkoutUrl": "https://checkout.waffo.ai/your-store/checkout/cs_xxx",
    "expiresAt": "2024-01-22T12:00:00Z"
  }
}

Redirect your customer to checkoutUrl to complete payment.

Redirect Best Practices

Do not use window.open() to open the checkout page. Safari and many mobile browsers block popup windows opened from asynchronous callbacks (e.g., after an API call). This causes checkout to silently fail for your customers.

Recommended approaches:

Method	When to Use	Example
Server-side redirect	API route / server action	`res.redirect(checkoutUrl)`
Client-side redirect	SPA / React	`window.location.href = checkoutUrl`
Link element	Static links	`<a href={checkoutUrl}>`

// ✅ Recommended: server-side redirect
export async function POST(req: NextRequest) {
  const session = await client.checkout.createSession({ ... });
  return NextResponse.redirect(session.checkoutUrl);
}

// ✅ Also fine: client-side redirect
const { checkoutUrl } = await res.json();
window.location.href = checkoutUrl;

// ❌ Avoid: window.open — blocked by Safari and mobile browsers
window.open(checkoutUrl, "_blank"); // Will be blocked!

After payment, the customer is redirected back to your successUrl. The successUrl is used as-is and no placeholders are replaced; to identify the purchase on your success page, add your own identifier (such as your internal order ID) to the successUrl query string before creating the session, and rely on webhooks to confirm the payment.

Pre-fill Customer Email

Skip the email input step by pre-filling it:

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
  buyerEmail: "user@example.com",
});

Use case: User is already logged into your app, so you know their email.

Tailor Checkout to Your Audience

Out of the box the hosted checkout is tuned for a global audience: it offers every payment method the currency supports, opens in the shopper’s browser language, and leaves the form blank. That is the right default when you sell everywhere. When most of your buyers come from one market, narrow it — a shopper who sees only the wallet they use every day, in their own language, with their email already filled in, is far less likely to hesitate or abandon. Four parameters on the checkout session control this. All of them are optional and independent:

Lever	Parameter	Effect
Currency	`currency`	Decides which payment methods exist at all — see the method and currency support table
Language	`language`	Default checkout UI language (BCP 47, e.g. `zh-Hans`, `ja-JP`, `ko-KR`). The shopper can still switch on the page
Payment methods	`includePaymentMethods` / `excludePaymentMethods`	Whitelist the methods your buyers recognize, or blacklist the ones you don’t want. Pass at most one of the two
Email	`buyerEmail`	Pre-fills the email field, so a logged-in buyer never wonders which address to type

Recipe

Price in the currency your buyers pay in. The currency, not the buyer’s location, decides which methods the checkout can offer. Check the support table before you pick.
Set language to the buyer’s locale. Skip it if your buyers are spread across markets — browser detection already handles that.
Narrow payment methods to what the market uses. For a single market use includePaymentMethods and list only what buyers there recognize. For several markets prefer excludePaymentMethods — values a currency does not offer are ignored, so one blacklist works across currencies.
Pre-fill buyerEmail whenever the buyer is logged in. Your buyer already has an account with you; asking for an email again invites hesitation (“do I use the same one?”). In authenticated checkout pass buyerIdentity and buyerEmail together.
Leave billingDetail out unless you need tax pre-fill. Passing it locks the checkout to that country’s payment market and the buyer cannot switch.

Examples

Mainland China

Buyers pay with WeChat Pay and read Simplified Chinese. WeChat Pay is available for one-time products priced in CNY or USD, up to about ¥1,000 (≈ $140) per order.

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "CNY",
  language: "zh-Hans",
  includePaymentMethods: ["wechat"],
  buyerEmail: user.email,
  successUrl: "https://yoursite.com/success?session_id={SESSION_ID}",
});

Subscriptions cannot use WeChat Pay, so for a subscription product drop includePaymentMethods and let the buyer pay by card.

Japan

Buyers expect JPY pricing and a Japanese UI. Cards and wallets all support JPY, so there is nothing to narrow — set the currency and language and keep the default methods.

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "JPY",
  language: "ja-JP",
  buyerEmail: user.email,
});

Multiple markets

Pick the configuration per buyer at request time from a signal you already have — the account’s country, the UI locale, or the plan they chose. Anything you cannot infer, leave out and let the checkout fall back to its defaults.

const MARKETS = {
  CN: { currency: "CNY", language: "zh-Hans", includePaymentMethods: ["wechat"] },
  JP: { currency: "JPY", language: "ja-JP" },
  DEFAULT: { currency: "USD" },
} as const;

const market = MARKETS[user.country as keyof typeof MARKETS] ?? MARKETS.DEFAULT;

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  ...market,
  buyerEmail: user.email,
});

Payment method filters need API Key authentication. includePaymentMethods and excludePaymentMethods are silently ignored on Store Slug sessions and on link-mode buttons — which method to offer is a merchant-side decision (fees, settlement), so it can only be made server-side. language and buyerEmail work in both modes.

Every value in includePaymentMethods must be supported by the product type × currency you send, or the request fails with 400 Payment methods not supported. A method can also be hidden at checkout for a single order — for example WeChat Pay above its per-order limit — so when you whitelist one method, make sure your prices stay inside its limits.

Track with Metadata

Link checkout sessions to your internal systems:

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
  metadata: {
    user_id: "usr_abc123",
    campaign: "black_friday_2024",
    referrer: "twitter",
  },
  successUrl: "https://yoursite.com/success",
});

Metadata is stored on the checkout session and is passed back in the orderMetadata field of webhook payloads. Merchant credentials (API Key) cannot query checkoutSession through GraphQL.

Subscription with Trial

Enable a trial period for subscription products:

const session = await client.checkout.createSession({
  productId: "prod_subscription",
  currency: "USD",
  withTrial: true,
  successUrl: "https://yoursite.com/welcome",
});

Per-seat quantities are not yet supported via the API. For one-time products, new subscriptions and plan changes, pass couponId to apply a coupon, promotionCode to pre-fill a code, or allowPromotionCodes: true to show a code entry field — see Discounts & Promotions.

Subscription with Billing Detail

Pre-fill the consumer’s billing information for tax calculation:

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
  billingDetail: {
    country: "US",
    isBusiness: false,
    state: "CA",
    postcode: "94105",
  },
});

Dynamic Success URL

Pass data to your success page:

const session = await client.checkout.createSession({
  productId: "prod_xxx",
  currency: "USD",
  successUrl: "https://yoursite.com/success?session_id={SESSION_ID}",
});

The redirect goes to successUrl as-is — placeholders such as {SESSION_ID} are not replaced. Build the identifiers you need into the URL yourself, and rely on webhooks to confirm the payment.

Complete Example: SaaS Upgrade Flow

Here’s a real-world example for upgrading a user’s subscription using the SDK:

// app/api/upgrade/route.ts (Next.js App Router)
import { NextRequest, NextResponse } from "next/server";
import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

export async function POST(req: NextRequest) {
  const { userId, planId, email } = await req.json();

  const session = await client.checkout.createSession({
    productId: planId,
    currency: "USD",
    buyerEmail: email,
    metadata: { user_id: userId, action: "upgrade" },
    successUrl: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard?upgraded=true`,
  });

  // Server-side redirect — works in all browsers
  return NextResponse.redirect(session.checkoutUrl);
}

If you need to handle checkout on the client side (e.g., SPA):

async function handleUpgrade(planId: string) {
  const res = await fetch("/api/upgrade", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userId: currentUser.id, planId, email: currentUser.email }),
  });
  const { checkoutUrl } = await res.json();

  // Redirect in same tab — Safari-safe
  window.location.href = checkoutUrl;
}

Parameters Reference

Parameter	Type	Required	Description
`productId`	string	Yes	Product UUID from Dashboard
`currency`	string	Yes	ISO 4217 currency code (e.g., `"USD"`)
`buyerEmail`	string	No	Pre-fill consumer email
`successUrl`	string	No	Custom success redirect URL
`metadata`	object	No	Custom key-value data stored on the session and returned in the webhook payload’s `orderMetadata` field
`withTrial`	boolean	No	Enable trial period for subscription products
`language`	string	No	Default checkout UI language (BCP 47 enum, e.g. `zh-Hans`, `ja-JP`); shopper can switch
`includePaymentMethods`	string[]	No	Whitelist of payment methods to offer (values such as `card`, `applepay`, `googlepay`, `wechat`, as registered on the platform); API Key only
`excludePaymentMethods`	string[]	No	Blacklist of payment methods to hide; mutually exclusive with the whitelist; API Key only
`billingDetail`	object	No	Pre-fill billing country/state/postcode for tax; locks the checkout to that country’s payment market
`darkMode`	boolean	No	Force dark or light theme; omit to use the store default

AI Integration

Business Models

Operations

What You’ll Build

Prerequisites

Basic Checkout Session

Using the TypeScript SDK (Recommended)

Using REST API Directly

Redirect Best Practices

Pre-fill Customer Email

Tailor Checkout to Your Audience

Recipe

Examples

Mainland China

Japan

Multiple markets

Track with Metadata

Subscription with Trial

Subscription with Billing Detail

Dynamic Success URL

Complete Example: SaaS Upgrade Flow

Parameters Reference

Next Steps

Handle Webhooks

Verify Payments

​What You’ll Build

​Prerequisites

​Basic Checkout Session

​Using the TypeScript SDK (Recommended)

​Using REST API Directly

​Redirect Best Practices

​Pre-fill Customer Email

​Tailor Checkout to Your Audience

​Recipe

​Examples

​Mainland China

​Japan

​Multiple markets

​Track with Metadata

​Subscription with Trial

​Subscription with Billing Detail

​Dynamic Success URL

​Complete Example: SaaS Upgrade Flow

​Parameters Reference

​Next Steps

Handle Webhooks

Verify Payments

What You’ll Build

Prerequisites

Basic Checkout Session

Using the TypeScript SDK (Recommended)

Using REST API Directly

Redirect Best Practices

Pre-fill Customer Email

Tailor Checkout to Your Audience

Recipe

Examples

Mainland China

Japan

Multiple markets

Track with Metadata

Subscription with Trial

Subscription with Billing Detail

Dynamic Success URL

Complete Example: SaaS Upgrade Flow

Parameters Reference

Next Steps