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

# Integration guide

> Complete your first payment in 5 minutes and quickly integrate Waffo Payments.

## Choose an integration path

Choose one path before you start. Both paths end with sandbox testing and submitting acceptance materials to the Waffo technical support group.

### API integration

Use this path if you already have your own checkout, need full server-side control, or want to integrate manually with the API Reference.

**1. Choose the payment product**

Use one-time payment for single-charge orders, or subscription payment for recurring billing.

**2. Integrate the required APIs**

Follow the [API direct](/docs/en/developer-docs/integration/api/overview.md) roadmap and implement the required APIs.

**3. Check API Reference details**

Use [API Reference](/docs/api-reference/introduction.md) for fields, requests, responses, and signing details.

**4. Complete extra payment setup**

If you need Apple Pay or Google Pay, complete the extra testing and configuration in [Sandbox and testing](/docs/en/developer-docs/getting-started/sandbox.md).

**5. Submit acceptance results**

Finish sandbox testing, download and fill in the acceptance case template, then submit the results to the Waffo technical support group.

### AI integration tool

Use this path if you want an AI coding tool to generate SDK integration code, tests, and a test report.

**1. Install waffo-integrate**

Run `npx @waffo/waffo-integrate`.

**2. Trigger the integration**

Trigger Waffo integration in Codex, Claude Code, or Cursor.

**3. Answer business questions**

Answer the AI's business questions, such as product type, refund, subscription, and whether Webhook integration is required.

**4. Review code and test report**

The AI generates code, runs integration tests, and outputs a test report.

**5. Submit the test report**

Submit the test report to the Waffo technical support group for confirmation.

## Recommended: Use the AI integration tool (waffo-integrate)

**waffo-integrate** is Waffo's official AI integration Skill. It uses an interactive wizard to generate production-ready SDK integration code, then checks the result through Step 6 verification. Version `1.7.0` supports Node.js, Java, Go, Python, and PHP projects.

### Installation

```bash Auto-detect (recommended) theme={null}
npx @waffo/waffo-integrate
```

```bash Codex theme={null}
npx @waffo/waffo-integrate --codex
```

```bash Shared agents theme={null}
npx @waffo/waffo-integrate --agents
```

```bash Claude Code theme={null}
npx @waffo/waffo-integrate --claude
```

```bash Cursor theme={null}
npx @waffo/waffo-integrate --cursor
```

### Usage

After installation, trigger it in your AI assistant:

* Type `integrate waffo`
* The Skill will guide you through: selecting a feature (payment / refund / subscription / Webhook) → detecting your language → generating code → running validation tests

### Supported languages and features

| Language | SDK | Frameworks |
| - | - | - |
| Node.js | `@waffo/waffo-node` | Express, NestJS, Fastify |
| Java | `com.waffo:waffo-java` | Spring Boot |
| Go | `github.com/waffo-com/waffo-go/v2` | Gin, Echo, Fiber, Chi |
| Python | `waffo` | FastAPI, Flask, Django |
| PHP | `waffo/waffo-php` | Laravel, Symfony, Slim, plain PHP |

All features can be integrated automatically via the Skill: payments, refunds, subscriptions (including upgrades and downgrades), Webhooks, merchant config queries, and payment method queries.

### Advantages

| Metric | Using the Skill | Manual integration |
| - | - | - |
| Eval coverage | 36 prompt scenarios / 117 assertions | Must maintain cases manually |
| Code generation rules | 33 guardrails | Must consult docs manually |
| Verification flow | Step 6 phased verification + report gate | Must organize acceptance manually |

> [!TIP]
>
> For full documentation, see [waffo-integrate on GitHub](https://github.com/waffo-com/waffo-integrate).

***

## Manual integration

If you prefer not to use an AI tool, follow these steps to integrate manually.

## Prerequisites

* Waffo Merchant account
* API Key (from the Dashboard)
* RSA key pair (see [Authentication and signing](/docs/en/developer-docs/integration/api/overview.md))

**1. Install the SDK**

```bash Node.js theme={null}
npm install @waffo/waffo-node
```

```xml Java theme={null}
<dependency>
    <groupId>com.waffo</groupId>
    <artifactId>waffo-java</artifactId>
    <version>3.1.0</version>
</dependency>
```

```bash Go theme={null}
go get github.com/waffo-com/waffo-go/v2
```

```bash Python theme={null}
python -m pip install "waffo==0.5.0b0"
# Or install the latest pre-release
python -m pip install --pre waffo
```

```bash PHP theme={null}
composer require waffo/waffo-php
```

**2. Initialize the client**

```typescript Node.js theme={null}
import { Waffo, Environment } from '@waffo/waffo-node';

const { WAFFO_API_KEY, WAFFO_PRIVATE_KEY, WAFFO_PUBLIC_KEY, WAFFO_MERCHANT_ID } = process.env;
if (!WAFFO_API_KEY || !WAFFO_PRIVATE_KEY || !WAFFO_PUBLIC_KEY || !WAFFO_MERCHANT_ID) {
  throw new Error('Set WAFFO_API_KEY, WAFFO_PRIVATE_KEY, WAFFO_PUBLIC_KEY, and WAFFO_MERCHANT_ID');
}

const waffo = new Waffo({
  apiKey: WAFFO_API_KEY,
  privateKey: WAFFO_PRIVATE_KEY,
  waffoPublicKey: WAFFO_PUBLIC_KEY,
  merchantId: WAFFO_MERCHANT_ID,
  environment: Environment.SANDBOX,
});
```

```java Java theme={null}
import com.waffo.Waffo;
import com.waffo.types.config.WaffoConfig;
import com.waffo.types.config.Environment;

WaffoConfig config = WaffoConfig.builder()
    .apiKey(System.getenv("WAFFO_API_KEY"))
    .privateKey(System.getenv("WAFFO_PRIVATE_KEY"))
    .waffoPublicKey(System.getenv("WAFFO_PUBLIC_KEY"))
    .merchantId(System.getenv("WAFFO_MERCHANT_ID"))
    .environment(Environment.SANDBOX)
    .build();

Waffo waffo = new Waffo(config);
```

```go Go theme={null}
import (
    "os"
    waffo "github.com/waffo-com/waffo-go/v2"
    "github.com/waffo-com/waffo-go/v2/config"
)

cfg, err := config.NewConfigBuilder().
    APIKey(os.Getenv("WAFFO_API_KEY")).
    PrivateKey(os.Getenv("WAFFO_PRIVATE_KEY")).
    WaffoPublicKey(os.Getenv("WAFFO_PUBLIC_KEY")).
    MerchantID(os.Getenv("WAFFO_MERCHANT_ID")).
    Environment(config.Sandbox).
    Build()
if err != nil {
    panic(err)
}

client := waffo.New(cfg)
```

```python Python theme={null}
import os

from waffo import Environment, Waffo, WaffoConfig

config = WaffoConfig(
    api_key=os.environ["WAFFO_API_KEY"],
    private_key=os.environ["WAFFO_PRIVATE_KEY"],
    waffo_public_key=os.environ["WAFFO_PUBLIC_KEY"],
    merchant_id=os.environ["WAFFO_MERCHANT_ID"],
    environment=Environment.SANDBOX,
)

waffo = Waffo(config)
```

```php PHP theme={null}
<?php

require __DIR__ . '/vendor/autoload.php';

use Waffo\Config\Environment;
use Waffo\Config\WaffoConfig;
use Waffo\Waffo;

$waffo = new Waffo(new WaffoConfig(
    apiKey: 'your-api-key',
    privateKey: 'your-base64-private-key',
    waffoPublicKey: 'waffo-base64-public-key',
    environment: Environment::Sandbox,
    merchantId: 'your-merchant-id',
));
```

**3. Create a payment**

```typescript theme={null}
import { randomUUID } from 'crypto';

const paymentRequestId = randomUUID().replace(/-/g, '');

const response = await waffo.order().create({
  paymentRequestId,
  merchantOrderId: `ORDER_${Date.now()}`,
  orderCurrency: 'HKD',
  orderAmount: '100.00',
  orderDescription: 'Premium Plan',
  notifyUrl: 'https://your-site.com/webhook/waffo',
  successRedirectUrl: 'https://your-site.com/payment/success',
  failedRedirectUrl: 'https://your-site.com/payment/failed',
  cancelRedirectUrl: 'https://your-site.com/payment/cancel',
  userInfo: {
    userId: 'user_123',
    userEmail: 'user@example.com',
    userTerminal: 'WEB',
  },
  paymentInfo: { productName: 'ONE_TIME_PAYMENT' },
  goodsInfo: {
    goodsName: 'Premium Plan',
    goodsUrl: 'https://your-site.com/product/001',
  },
});

if (response.isSuccess()) {
  const data = response.getData();
  // Redirect the user to the Waffo checkout page
  redirect(data.orderAction);
}
```

**4. Handle the Webhook callback**

See the [Webhook](/docs/en/developer-docs/webhook/overview.md) section.

## Next steps


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.