> ## 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 Waffo SDK integration with AI coding tools—33% faster than manual integration, with a 100% success rate.

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 Claude Code and Cursor.

## Integration roadmap

<Steps>
  <Step title="Prepare your project">
    Open your project in Claude Code or Cursor.
  </Step>

  <Step title="Install the Skill">
    Run `npx @waffo/waffo-integrate`.
  </Step>

  <Step title="Trigger Waffo integration">
    Ask your AI assistant to integrate Waffo payment.
  </Step>

  <Step title="Answer business questions">
    Select the capabilities you need, such as payment, refund, subscription, Webhook, merchant configuration lookup, and payment method lookup.
  </Step>

  <Step title="Review and generate code">
    The AI tool previews the code, then generates SDK initialization, services, Webhook handlers, and tests after confirmation.
  </Step>

  <Step title="Run verification">
    The AI tool runs integration tests covering payment, refund, subscription, and Webhook flows.
  </Step>

  <Step title="Submit the test report">
    Send the generated test report to the Waffo technical support group for confirmation.
  </Step>
</Steps>

## Why use waffo-integrate

| Metric                | Using the Skill | Manual integration | Improvement |
| --------------------- | --------------- | ------------------ | ----------- |
| Integration pass rate | **100%**        | 75%                | +25%        |
| Average time          | 128s            | 192s               | -33%        |
| Token usage           | 58.8k           | 66.3k              | -11%        |

## Installation

<CodeGroup>
  ```bash Automatic detection (recommended) theme={null}
  npx @waffo/waffo-integrate
  ```

  ```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
  ```
</CodeGroup>

## Integration flow

<Steps>
  <Step title="Trigger the Skill">
    Enter a trigger phrase in your AI assistant: `集成 Waffo 支付`, `integrate waffo`, `接入waffo`, `waffo sdk`, or `waffo payment`.
  </Step>

  <Step title="Language detection">
    The Skill automatically detects the project language: `package.json` → Node.js, `pom.xml` / `build.gradle` → Java, `go.mod` → Go.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Framework selection (Webhook only)">
    | Language | Recommended framework | Other options    |
    | -------- | --------------------- | ---------------- |
    | Node.js  | Express               | NestJS, Fastify  |
    | Java     | Spring Boot           | —                |
    | Go       | Gin                   | Echo, Fiber, Chi |
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Integration verification (optional)">
    Run 15 acceptance tests covering the full payments, refunds, and subscriptions flow. Includes HTTP endpoint tests + Playwright automated checkout operations + database state checks.
  </Step>
</Steps>

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.

## 13 built-in API rules

The Skill’s built-in rules automatically prevent common mistakes:

| #  | 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 + sign the response   | 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                                  |

## Generated code features

* **Error handling**: distinguishes between `WaffoUnknownStatusError` (may have succeeded) and `WaffoError` (client error)
* **Security**: Webhook signature verification + response signing, 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).