Create Checkout Session
Create a checkout session that locks product version, pricing, and currency. This is the first step in the checkout flow for both one-time and subscription products.
POST /v1/actions/checkout/create-session
Request Body (API Key)
| Field | Type | Required | Description |
|---|
storeId | string | Yes | UUID of the store |
productId | string | Yes | UUID of the product |
productType | string | Yes | onetime or subscription |
currency | string | Yes | ISO 4217 currency code |
withTrial | boolean | No | Enable trial period (subscriptions only) |
buyerEmail | string | No | Pre-fill buyer’s email |
billingDetail | object | No | Pre-fill billing details |
successUrl | string | No | Override redirect URL on success |
expiresInSeconds | number | No | Custom session TTL |
metadata | object | No | Custom key-value data |
priceSnapshot | object | No | Override pricing (API Key only) |
Request Body (Store Slug)
| Field | Type | Required | Description |
|---|
productId | string | Yes | UUID of the product |
productType | string | Yes | onetime or subscription |
currency | string | Yes | ISO 4217 currency code |
billingDetail | object | No | Pre-fill billing details |
buyerEmail | string | No | Pre-fill buyer’s email |
withTrial | boolean | No | Enable trial period |
successUrl | string | No | Override redirect URL |
metadata | object | No | Custom key-value data |
Store Slug authentication does not support priceSnapshot to prevent price tampering from the client side.
Example Request
import { WaffoPancake, CheckoutSessionProductType } 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({
storeId: "store-uuid",
productId: "product-uuid",
productType: CheckoutSessionProductType.Onetime,
currency: "USD",
buyerEmail: "customer@example.com",
successUrl: "https://example.com/thank-you",
});
// => session.checkoutUrl, session.sessionId, session.expiresAt
Success Response
{
"data": {
"sessionId": "session-uuid",
"checkoutUrl": "https://checkout.waffo.ai/store-slug/checkout/session-uuid",
"expiresAt": "2026-01-22T10:30:00.000Z"
}
}
Checkout sessions have a 7-day TTL. The session locks the product version and pricing at creation time, so price changes won’t affect existing sessions.
Preview Tax
Preview tax calculation for a checkout session before creating the order.
POST /v1/actions/checkout/preview-tax
Request Body
| Field | Type | Required | Description |
|---|
checkoutSessionId | string | Yes | UUID of the checkout session |
billingDetail | object | Yes | Billing details for tax calculation |
Billing Detail
| Field | Type | Required | Description |
|---|
country | string | Yes | ISO 3166-1 alpha-2 country code |
isBusiness | boolean | Yes | Whether this is a business purchase |
state | string | Conditional | Required for US, CA |
businessName | string | No | Business name |
taxId | string | No | Tax ID (for EU B2B exemption) |
Success Response
{
"data": {
"subtotal": 2900,
"taxAmount": 261,
"total": 3161,
"taxRate": 0.09
}
}
Create One-Time Order
Create an order for a one-time product using a checkout session.
POST /v1/actions/onetime-order/create-order
Request Body
| Field | Type | Required | Description |
|---|
checkoutSessionId | string | Yes | UUID of the checkout session |
billingDetail | object | Yes | Billing details |
buyerEmail | string | No | Buyer’s email address |
buyerIp | string | No | Buyer’s IP address (for tax calculation) |
successUrl | string | No | Override redirect URL on success |
Billing Detail
| Field | Type | Required | Description |
|---|
country | string | Yes | ISO 3166-1 alpha-2 country code |
isBusiness | boolean | Yes | Whether this is a business purchase |
state | string | Conditional | Required for US, CA |
postcode | string | No | Postal/ZIP code |
businessName | string | No | Business name (when isBusiness: true) |
taxId | string | No | Tax ID (required for EU B2B) |
Example Request
curl -X POST https://waffo-pancake-auth-service.vercel.app/v1/actions/onetime-order/create-order \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
-d '{
"checkoutSessionId": "session-uuid",
"billingDetail": {
"country": "US",
"isBusiness": false,
"state": "CA",
"postcode": "94105"
},
"buyerEmail": "customer@example.com"
}'
Success Response
{
"data": {
"checkoutUrl": "https://checkout.waffo.ai/store-slug/checkout/token"
}
}
Redirect the buyer to checkoutUrl to complete payment. The checkout page handles payment collection, tax calculation, and 3D Secure authentication.
Cancel One-Time Order
Cancel a pending (unpaid) order.
POST /v1/actions/onetime-order/cancel-order
Request Body
| Field | Type | Required | Description |
|---|
orderId | string | Yes | UUID of the order to cancel |
Success Response
{
"data": {
"orderId": "order-uuid",
"status": "canceled"
}
}
Only orders with pending status can be canceled. Completed orders require a refund request instead.
One-Time Order Status Values
| Status | Description |
|---|
pending | Order created, payment not yet completed |
completed | Payment successful, order fulfilled |
canceled | Order canceled before payment |
