API Reference

Integrate Waffo Pancake into your application

Overview

The Waffo Pancake API lets you programmatically manage your entire payment infrastructure:

• Create and manage stores
• Create products (one-time and subscription)
• Generate checkout sessions and process orders
• Manage subscriptions and billing
• Query data via GraphQL
• Handle refunds

Base URL

All API requests are made to:

https://api.waffo.ai/v1

Architecture

The API uses a hybrid approach:

• REST endpoints (/v1/actions/...) for all write operations (create, update, delete)
• GraphQL (/v1/graphql) for all read operations (queries)

All REST endpoints use POST method exclusively. There are no GET, PUT, PATCH, or DELETE methods.

TypeScript SDK

The official @waffo/pancake-ts SDK wraps the entire API with full type safety. It handles authentication, request signing, idempotency keys, and webhook verification automatically.

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!,
});

Every endpoint documented below includes an SDK example alongside the REST/cURL examples. Full SDK documentation ->

---

Authentication

Waffo Pancake uses API Key authentication for all programmatic API access. API Key authentication is handled automatically by the SDK.

For public-facing checkout flows, use Store Slug authentication with the X-Store-Slug header.

Learn more about authentication ->

---

Common Headers

Header	Required	Description
Content-Type	Yes	Always application/json
X-Store-Slug	Conditional	Store slug (for public checkout flows)
X-Environment	Conditional	test or prod (required with Store Slug auth, not needed for API Key)
X-Idempotency-Key	Optional	Globally unique ID per write operation (cached 24h)

API Key authentication headers (X-Merchant-Id, X-Timestamp, X-Signature) are handled automatically by the SDK. You only need to provide your Merchant ID and private key when initializing the client.

---

Request Format

• Method: All write endpoints use POST
• Body: JSON
• Timestamps: ISO 8601 UTC (e.g., 2026-01-23T00:00:00.000Z)
• Amounts: Display format strings (e.g., "29.00" = $29.00 USD)
• Currencies: ISO 4217 codes (e.g., USD, EUR, JPY)
• Status values: Always lowercase (e.g., active, not ACTIVE)

ID Formats

All externally-facing entity IDs use Short ID format: {PREFIX}_{base62}.

Prefix	Entity	Example
MER	Merchant	MER_2D5F8G3H1K4M6N9P
STO	Store	STO_3bVzrkD0FJjFdZNLk8Ualx
PROD	Product / Version	PROD_4cWAslE1GKkGeaOMl9Vbmy
ORD	Order	ORD_5dXBtmF2HLlHfbPNm0Wcnz
PAY	Payment	PAY_6eYCunG3IMmIgcQOnaXdoA
REF	Refund	REF_7fZDvoH4JNnJhdRPobYepB
TKT	Ticket	TKT_8gAEwpI5KOoKieSQL1ZfqC
KEY	API Key	KEY_4F7H0I5J3K6M8N1P

Checkout Session IDs use a special format: cs_ + UUID (e.g., cs_550e8400-e29b-41d4-a716-446655440000). They are not part of the Short ID system.

---

Response Format

Success

{
  "data": {
    "store": {
      "id": "STO_3bVzrkD0FJjFdZNLk8Ualx",
      "name": "My Store",
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  }
}

Error

{
  "data": null,
  "errors": [
    {
      "message": "Store slug already exists",
      "layer": "store"
    }
  ]
}

In the errors array, errors[0] is the root cause of the failure. Subsequent entries represent higher-level callers in the request chain.

Error layer Field

Each error includes a layer string indicating which part of the system produced the error. Use this to identify the root cause when debugging. The value is always one of the predefined layer names (e.g., "gateway", "store", "product").

---

HTTP Status Codes

Code	Description
200	Success
400	Bad Request — invalid parameters
401	Unauthorized — authentication failed
403	Forbidden — insufficient permissions
404	Not Found
409	Conflict — idempotent request already in progress
429	Rate Limited — too many requests
500	Internal Server Error
501	Not Implemented
502	Bad Gateway

---

Environments

API Key authentication determines the environment automatically based on which key verifies successfully. Store Slug authentication requires the X-Environment header:

Environment	Header Value	Description
Test	X-Environment: test	No real charges, isolated data
Production	X-Environment: prod	Real transactions

---

Idempotency

Prevent duplicate write operations by including an X-Idempotency-Key header:

Item	Specification
Header	X-Idempotency-Key
Uniqueness	Globally unique per request within your merchant account
Max length	256 characters
Allowed chars	Letters, numbers, hyphens (-), underscores (_)
Cache duration	24 hours

Let the SDK generate the key when you can — it derives a deterministic hash from merchantId + path + body, so it is unique per request by construction. If you build the key yourself, combine your merchantId with a UUID:

X-Idempotency-Key: MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67

A short, guessable key can match one already used by a different request, in which case you receive that request’s cached response. See Errors -> Idempotency for Safe Retries for the full requirement.

Scenario	Behavior	Status
First request	Executes normally, caches 2xx response	Original
Duplicate (completed)	Returns cached response without re-executing	Original
Duplicate (in progress)	Returns conflict error	409
Original failed (non-2xx)	Same key can be retried	—

---

Endpoint Groups

Authentication

Issue session tokens for checkout flows

Stores

Create, update, and delete stores

One-Time Products

Create and manage one-time purchase products

Subscription Products

Create tiered subscription products and groups

Orders

Create checkout sessions and orders

Subscriptions

Manage subscription lifecycle

Refunds

Request and process refunds

GraphQL

Query all data with GraphQL