> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> Choose the right integration path for your application

## Choose Your Integration Path

<CardGroup cols={3}>
  <Card title="AI Integration" icon="sparkles" href="/integrate/ai-integration">
    **Fastest to ship**

    Best for teams with an existing codebase that want Claude Code or another coding agent to plan the model, implement the integration, and drive validation.
  </Card>

  <Card title="API / SDK" icon="code" href="/integrate/sdks">
    **Most control**

    Best when you need custom checkout flows, server-side orchestration, dynamic pricing, or tighter control over integration behavior.
  </Card>

  <Card title="Hosted Checkout" icon="link" href="/quickstart">
    **Simplest**

    Best when you want to launch a payment link quickly first and deepen the integration later.
  </Card>
</CardGroup>

***

## 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                                              |

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

***

## 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
```

<Note>
  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.
</Note>

***

## 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

<Steps>
  <Step title="Create Account">
    Sign up at [Merchant Dashboard](https://pancake.waffo.ai/merchant/auth/signin) and create your first store.
  </Step>

  <Step title="Set Up Authentication">
    Prepare your Merchant ID and API Key in the merchant dashboard.
  </Step>

  <Step title="Create Products">
    Define the product type, pricing, and billing interval, then create products via the Dashboard or API.
  </Step>

  <Step title="Implement Checkout">
    Create checkout sessions through the API, or use Dashboard-generated checkout links.
  </Step>

  <Step title="Handle Webhooks">
    Set up webhook endpoints for payment, refund, and subscription events.
  </Step>

  <Step title="Test End-to-End">
    Use [Test Mode](/features/test-mode) with test cards to verify the full flow.
  </Step>

  <Step title="Go Live">
    Publish products and switch to the production environment.
  </Step>
</Steps>

***

## 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

<Tip>
  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.
</Tip>

***

## Core Entry Points

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/integrate/authentication">
    Configure Merchant ID, API Key, and server-side authentication.
  </Card>

  <Card title="Test Mode" icon="flask" href="/features/test-mode">
    Test the full integration flow without real charges.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integrate/webhooks">
    Receive real-time events and keep orders and subscriptions in sync.
  </Card>

  <Card title="SDKs" icon="code" href="/integrate/sdks">
    Browse official SDKs, framework patterns, and code samples.
  </Card>

  <Card title="AI Integration" icon="sparkles" href="/integrate/ai-integration">
    Use an AI coding assistant for planning, implementation, and validation.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Start from the first payment flow and learn the end-to-end path quickly.
  </Card>
</CardGroup>

***

## Developer Settings

The API & Development 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.

<CardGroup cols={2}>
  <Card title="Test Keys" icon="flask">
    * Created for `test` environment
    * Use for development
    * No real charges
    * Separate from production data
  </Card>

  <Card title="Live Keys" icon="key">
    * Created for `prod` environment
    * Use for production
    * Process real payments
    * Keep private key secure
  </Card>
</CardGroup>

### Key Types

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

### API Key Authentication

<Note>
  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.
</Note>

```typescript theme={"system"}
import { WaffoPancake } from "@waffo/pancake-ts";

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

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

### Creating API Keys

<Steps>
  <Step title="Navigate to API & Development">
    Go to Dashboard --> API & Development --> API Keys
  </Step>

  <Step title="Click 'Create API Key'">
    The API Key Generator opens.
  </Step>

  <Step title="Generate Key Pair">
    Click "Generate" to create a key pair.

    * Public key is sent to the server
    * Private key stays with you
  </Step>

  <Step title="Name Your Key">
    Give it a descriptive nickname (e.g., "Production Server").
  </Step>

  <Step title="Select Environment">
    Choose **Test** or **Production** environment.
  </Step>

  <Step title="Download Private Key">
    **Critical:** Download and securely store your private key.
  </Step>
</Steps>

<Warning>
  Your private key is only shown once. Store it securely -- you will need it for API authentication.
</Warning>

### 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

<Steps>
  <Step title="Add Endpoint">
    Enter your webhook URL (must be HTTPS).
  </Step>

  <Step title="Select Events">
    Choose which events to receive.
  </Step>

  <Step title="Save Configuration">
    Save your webhook endpoint.
  </Step>
</Steps>

### Webhook Payload Example

```json theme={"system"}
{
  "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"
  }
}
```

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

### Webhook Best Practices

<AccordionGroup>
  <Accordion title="Respond Quickly">
    Return 2xx status within 30 seconds. Process heavy work asynchronously.
  </Accordion>

  <Accordion title="Handle Duplicates">
    Events may be sent multiple times. Use event IDs for deduplication.
  </Accordion>

  <Accordion title="Retry Logic">
    Failed webhooks retry up to 5 times with increasing delays (5min, 30min, 2h, 24h).
  </Accordion>

  <Accordion title="Monitor Failures">
    Check webhook delivery logs in the Dashboard for failures.
  </Accordion>
</AccordionGroup>

## API Documentation

### Base URL

```
https://api.waffo.ai/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:**

```typescript theme={"system"}
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)         |

<Card title="Full API Reference" icon="code" href="/api-reference/introduction">
  Complete endpoint documentation with request/response examples.
</Card>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Environment Variables" icon="lock">
    Store private keys in environment variables, never in code.
  </Card>

  <Card title="Key Rotation" icon="rotate">
    Regularly rotate keys, especially after team changes.
  </Card>

  <Card title="Separate Keys" icon="shield">
    Use different API keys for test and production environments.
  </Card>

  <Card title="Secure Storage" icon="vault">
    Store private keys using your platform's secret management.
  </Card>
</CardGroup>

## 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