Integrations - Waffo Pancake

Choose Your Integration Path

AI Integration

Fastest to shipBest for teams with an existing codebase that want Claude Code or another coding agent to plan the model, implement the integration, and drive validation.

API / SDK

Most controlBest when you need custom checkout flows, server-side orchestration, dynamic pricing, or tighter control over integration behavior.

Hosted Checkout

SimplestBest when you want to launch a payment link quickly first and deepen the integration later.

How To Choose

If you care most about	Recommended path	Why
Shipping the first usable version quickly	AI Integration	Best when you want a coding agent to turn an existing codebase into a working integration fast
Full control over payment flow and server logic	API / SDK	Best for custom checkout, dynamic pricing, permissions, and internal orchestration
Validating the payment funnel before deeper engineering	Hosted Checkout	Best for low engineering overhead and fast launch

Many teams start with Hosted Checkout or AI Integration for the first version, then move deeper into the API / SDK path as requirements grow.

What An Integration Usually Includes

Most Waffo Pancake integrations include four parts:

Authentication for server-side requests
Products and checkout for one-time or subscription billing
Webhooks for payment and subscription events
Environment rollout from test mode to production

Your application
    |
    +-- Authentication --> API / SDK requests
    |
    +-- Product + Checkout --> Payments
    |
    +-- Webhooks --> Order and subscription sync

You do not need every layer on day one. Many teams start with hosted checkout or AI-assisted integration, then deepen their API usage later.

What Each Path Usually Delivers

AI Integration

let an AI coding assistant read llms-full.txt and the official skill context
generate integration code, webhook handling, and validation steps for your stack
best when you already have a codebase and want to shorten implementation time

API / SDK

gives your server full control over products, checkout, webhooks, and state sync
fits dynamic pricing, fine-grained permissions, and custom backend orchestration
best for long-term customization and more complex billing logic

Hosted Checkout

use dashboard-generated checkout links or public payment entry points directly
best for validating the commercial flow before investing in deeper engineering
usually the best first-stage integration path

Recommended Rollout Order

Create Account

Set Up Authentication

Prepare your Merchant ID and API Key in the merchant dashboard.

Create Products

Define the product type, pricing, and billing interval, then create products via the Dashboard or API.

Implement Checkout

Create checkout sessions through the API, or use Dashboard-generated checkout links.

Handle Webhooks

Set up webhook endpoints for payment, refund, and subscription events.

Test End-to-End

Use Sandbox Environment with test cards to verify the full flow.

Go Live

Publish products and switch to the production environment.

What To Prepare Before Implementation

Before writing code, define these clearly:

whether you sell one-time products, subscriptions, or both
whether you need dynamic pricing for overage, credits, or quoted amounts
what access, entitlements, or resources should be granted after payment
which webhook events should drive your business state changes
which capabilities should stay in test mode until production rollout

If these decisions are still fuzzy, start with the AI Integration path. If these rules are already well-defined, the API / SDK path is usually the stronger choice.

Core Entry Points

Authentication

Configure Merchant ID, API Key, and server-side authentication.

Sandbox Environment

Test the full integration flow without real charges.

Webhooks

Receive real-time events and keep orders and subscriptions in sync.

SDKs

Browse official SDKs, framework patterns, and code samples.

AI Integration

Use an AI coding assistant for planning, implementation, and validation.

Quickstart

Start from the first payment flow and learn the end-to-end path quickly.

Developer Settings

The Developers page provides tools for integrating Waffo Pancake with your applications.

API Keys

Overview

API keys authenticate server-to-server requests to the Waffo Pancake API.

Test Keys

Created for test environment
Use for development
No real charges
Separate from production data

Live Keys

Created for prod environment
Use for production
Process real payments
Keep private key secure

Key Types

Key Type	Use Case	Description
API Key	Server-side only	Signed requests for full API access

API Key Authentication

API Key authentication is handled automatically by the SDK. Install @waffo/pancake-ts, provide your Merchant ID and private key, and the SDK will handle request signing automatically.

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

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

Never expose your private key in client-side code, version control, or public repositories.

Creating API Keys

Navigate to Developers

Go to Dashboard —> Developers —> API Keys

Click 'Create API Key'

The API Key Generator opens.

Generate Key Pair

Click “Generate” to create a key pair.

Public key is sent to the server
Private key stays with you

Name Your Key

Give it a descriptive nickname (e.g., “Production Server”).

Select Environment

Choose Test or Production environment.

Download Private Key

Critical: Download and securely store your private key.

Your private key is only shown once. Store it securely — you will need it for API authentication.

Managing Keys

Action	Description
View	See key nickname, creation date, environment
Delete	Permanently remove the key

Webhooks

What Are Webhooks?

Webhooks notify your server when events occur in Waffo Pancake.

Available Events

Event	Trigger
`order.completed`	Order completed
`subscription.activated`	Subscription activated
`subscription.payment_succeeded`	Subscription payment succeeded
`subscription.updated`	Subscription updated
`subscription.canceling`	Subscription cancellation scheduled
`subscription.canceled`	Subscription ended
`subscription.uncanceled`	Subscription cancellation reversed
`subscription.past_due`	Subscription payment past due
`refund.succeeded`	Refund processed successfully
`refund.failed`	Refund processing failed

Setting Up Webhooks

Add Endpoint

Enter your webhook URL (must be HTTPS).

Select Events

Choose which events to receive.

Save Configuration

Save your webhook endpoint.

Webhook Payload Example

{
  "event": "order.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "660e8400-e29b-41d4-a716-446655440001",
    "amount": 2900,
    "currency": "USD",
    "status": "completed",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

All IDs are UUID v4 format. Amounts are in the smallest currency unit. Timestamps are ISO 8601 UTC.

Webhook Best Practices

Respond Quickly

Return 2xx status within 30 seconds. Process heavy work asynchronously.

Handle Duplicates

Events may be sent multiple times. Use event IDs for deduplication.

Retry Logic

Failed webhooks retry up to 5 times with increasing delays (5min, 30min, 2h, 24h).

Monitor Failures

Check webhook delivery logs in the Dashboard for failures.

API Documentation

Base URL

https://waffo-pancake-auth-service.vercel.app/v1

Architecture

Waffo Pancake uses a hybrid API:

REST (POST) for all write operations via /v1/actions/...
GraphQL for all read operations via /v1/graphql

Authentication Example

API Key (Server-to-Server) using SDK:

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

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

const { store } = await client.stores.create({ name: "My Store" });

Common Endpoints

Endpoint	Method	Description
`/v1/actions/onetime-product/create-product`	POST	Create one-time product
`/v1/actions/subscription-product/create-product`	POST	Create subscription product
`/v1/actions/onetime-order/create-order`	POST	Create checkout session
`/v1/actions/subscription-order/create-order`	POST	Create subscription checkout
`/v1/graphql`	POST	Query data (GraphQL)

Full API Reference

Complete endpoint documentation with request/response examples.

Security Best Practices

Environment Variables

Store private keys in environment variables, never in code.

Key Rotation

Regularly rotate keys, especially after team changes.

Separate Keys

Use different API keys for test and production environments.

Secure Storage

Store private keys using your platform’s secret management.

Testing

Test Mode

Use test mode for development:

All endpoints work identically
No real charges processed
Test card numbers available
Full webhook testing

Test Cards

Card Number	Behavior
`4576 7500 0000 0110`	Success (Visa)
`2226 9000 0000 0110`	Success (Mastercard)
`4576 7500 0000 0220`	Declined

Logs and Debugging

Webhook Logs

Track webhook deliveries:

Event type
Delivery status (success/failed)
HTTP response from your endpoint
Retry attempts and timestamps

Get Started

Features

Merchant

Store

Merchant of Record

Documentation Index

​Choose Your Integration Path

AI Integration

API / SDK

Hosted Checkout

​How To Choose

​What An Integration Usually Includes

​What Each Path Usually Delivers

​AI Integration

​API / SDK

​Hosted Checkout

​Recommended Rollout Order

​What To Prepare Before Implementation

​Core Entry Points

Authentication

Sandbox Environment

Webhooks

SDKs

AI Integration

Quickstart

​Developer Settings

​API Keys

​Overview

Test Keys

Live Keys

​Key Types

​API Key Authentication

​Creating API Keys

​Managing Keys

​Webhooks

​What Are Webhooks?

​Available Events

​Setting Up Webhooks

​Webhook Payload Example

​Webhook Best Practices

​API Documentation

​Base URL

​Architecture

​Authentication Example

​Common Endpoints

Full API Reference

​Security Best Practices

Environment Variables

Key Rotation

Separate Keys

Secure Storage

​Testing

​Test Mode

​Test Cards

​Logs and Debugging

​Webhook Logs

Choose Your Integration Path

How To Choose

What An Integration Usually Includes

What Each Path Usually Delivers

AI Integration

API / SDK

Hosted Checkout

Recommended Rollout Order

What To Prepare Before Implementation

Core Entry Points

Developer Settings

API Keys

Overview

Key Types

API Key Authentication

Creating API Keys

Managing Keys

Webhooks

What Are Webhooks?

Available Events

Setting Up Webhooks

Webhook Payload Example

Webhook Best Practices

API Documentation

Base URL

Architecture

Authentication Example

Common Endpoints

Security Best Practices

Testing

Test Mode

Test Cards

Logs and Debugging

Webhook Logs