> ## 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.
"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).
## Integration roadmap
Open your project in Codex, Claude Code, or Cursor.
Run `npx @waffo/waffo-integrate`.
Ask your AI assistant to integrate Waffo payment.
Select the capabilities you need, such as payment, refund, subscription, Webhook, merchant configuration lookup, and payment method lookup.
The AI tool previews the code, then generates SDK initialization, services, Webhook handlers, and tests after confirmation.
The AI tool runs integration tests covering payment, refund, subscription, and Webhook flows.
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
Enter a trigger phrase in your AI assistant: `集成 Waffo 支付`, `integrate waffo`, `接入waffo`, `waffo sdk`, or `waffo payment`.
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.
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.
| 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 |
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`.
Run Step 6 phased acceptance tests covering payments, refunds, and subscriptions. Includes HTTP endpoint tests + Playwright automated checkout operations + database state checks.
After verification, send the generated 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).