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

# AI integration tool (waffo-integrate)

> Automatically complete and verify Waffo SDK integration with AI coding tools.

waffo-integrate is Waffo’s official AI integration Skill. It helps developers automatically complete SDK integration through an interactive wizard. It supports AI coding tools such as Codex, Claude Code, and Cursor. Version `1.7.0` supports Node.js, Java, Go, Python, and PHP projects.

> [!NOTE]
>
> "AI" on this page means using AI coding tools to complete SDK integration. If you want to accept stablecoin payments from AI Agents, see [x402 stablecoin acquiring](/docs/en/developer-docs/use-cases/x402-stablecoin-acquiring.md).

## Integration roadmap

**1. Prepare your project**

Open your project in Codex, Claude Code, or Cursor.

**2. Install the Skill**

Run `npx @waffo/waffo-integrate`.

**3. Trigger Waffo integration**

Ask your AI assistant to integrate Waffo payment.

**4. Answer business questions**

Select the capabilities you need, such as payment, refund, subscription, Webhook, merchant configuration lookup, and payment method lookup.

**5. Review and generate code**

The AI tool previews the code, then generates SDK initialization, services, Webhook handlers, and tests after confirmation.

**6. Run verification**

The AI tool runs integration tests covering payment, refund, subscription, and Webhook flows.

**7. Submit the test report**

Send the generated test report to the Waffo technical support group for confirmation.

## Why use waffo-integrate

| Metric | Using the Skill | Manual integration | Improvement |
| - | - | - | - |
| Eval coverage | 36 prompt scenarios / 117 assertions | Manual case maintenance | Automated regression |
| Code generation rules | 33 guardrails | Manual doc lookup | Automatic prevention |
| Verification flow | Step 6 phased verification + report gate | Self-organized acceptance | Evidence-based closure |

## Installation

```bash Automatic detection (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
claude /install-skill waffo-com/waffo-integrate
```

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

## Integration flow

**1. Trigger the Skill**

Enter a trigger phrase in your AI assistant: `集成 Waffo 支付`, `integrate waffo`, `接入waffo`, `waffo sdk`, or `waffo payment`.

**2. Language detection**

The Skill automatically detects the project language: `package.json` → Node.js, `pom.xml` / `build.gradle` → Java, `go.mod` → Go, `pyproject.toml` / `requirements.txt` / `Pipfile` / `uv.lock` / `setup.py` → Python, and `composer.json` → PHP.

**3. Feature selection**

Interactively select the features you need (prompted one by one): payments, refunds, subscriptions, Webhook, merchant configuration lookup, payment method lookup. Smart recommendations: if you select payments, it will suggest adding refunds; if you select subscriptions, it will suggest adding Webhook.

**4. Framework selection (Webhook only)**

| Language | Recommended framework | Other options |
| - | - | - |
| Node.js | Express | NestJS, Fastify |
| Java | Spring Boot | — |
| Go | Gin | Echo, Fiber, Chi |
| Python | FastAPI | Flask, Django |
| PHP | Laravel | Symfony, Slim, plain PHP |

**5. Code preview & generation**

The Skill first displays the complete code for review, then generates it after confirmation: SDK initialization, payment/refund/subscription services, Webhook handling, test files, and `.env.example`.

**6. Integration verification**

After code generation and build pass, the Skill runs Step 6 phased acceptance tests for the features you integrate and records results and evidence. It generates a formal test report only after the required stages and evidence are complete. If evidence is missing or tests fail, it outputs `Verification Blocked` or `Failed Summary`, without marking incomplete verification as passed.

See [Integration acceptance criteria](/docs/en/developer-docs/tools-and-references/references/acceptance-criteria.md) for requirements and case templates.

After verification passes, send the formal test report to your company and Waffo technical support group, such as the WeCom or Lark group, so Waffo can confirm the integration result.

## 33 built-in code generation rules

The Skill’s built-in rules automatically prevent common mistakes. The complete list lives in `references/code-generation-rules.md`:

| # | Rule | Prevents |
| - | - | - |
| 1 | Request ID max length is 32 characters | Values longer than the Waffo idempotency key limit |
| 2 | Subscriptions use `currency`, not `orderCurrency` | Field name confusion |
| 3 | Subscriptions use `amount`, not `orderAmount` | Field name confusion |
| 4 | Required-field checks for each operation | Missing `payMethodType`, `goodsInfo`, etc. |
| 5 | `periodType` is only DAILY/WEEKLY/MONTHLY | Invalid enums `YEARLY`, `MONTH` |
| 6 | `periodInterval` is String, not Number | Type errors |
| 7 | Subscriptions must include `payMethodType` | SDK error A0003 |
| 8 | `productName` is only ONE\_TIME\_PAYMENT / SUBSCRIPTION | Invalid product type |
| 9 | Use `isSuccess()` to check responses | Missing error handling |
| 10 | Webhook must verify the signature | Security vulnerability |
| 11 | Java uses `WaffoConfig.builder()` | SDK initialization failure |
| 12 | Timestamps are auto-injected by the SDK | Incorrect manual timestamp format |
| 13 | merchantId is auto-injected by the SDK | Duplicate setting |
| 14-33 | Webhook three-stage business handling, UnknownStatus recovery for every write operation, redirect URLs, goodsInfo, payment method, currency, refund notification URL, and report-evidence guardrails | Missing money-state handling, redirects, risk-control fields, or report evidence |

## Generated code features

* **Error handling**: distinguishes between `WaffoUnknownStatusError` (may have succeeded) and `WaffoError` (client error)
* **Security**: Webhook signature verification and credential management via environment variables
* **Best practices**: idempotent request IDs, service-layer separation, register Webhook before parsing JSON
* **Testing**: sandbox integration test stubs, test card numbers

For detailed documentation, see [waffo-integrate GitHub](https://github.com/waffo-com/waffo-integrate).


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