# Waffo Documentation

- [Guides (121 pages)](https://waffo.com/docs/_llms/en/guides.txt): Documentation for Guides.

## Developer

### Getting Started

- [Integration overview](https://waffo.com/docs/en/developer-docs/getting-started/overview.md): An overview of Waffo's core capabilities and integration flow as a one-stop global payments platform.
- [Integration guide](https://waffo.com/docs/en/developer-docs/getting-started/quickstart.md): Complete your first payment in 5 minutes and quickly integrate Waffo Payments.
- [Sandbox and testing](https://waffo.com/docs/en/developer-docs/getting-started/sandbox.md): Complete full integration testing in the sandbox environment without real funds.

#### Production go-live

- [Production go-live](https://waffo.com/docs/en/developer-docs/getting-started/go-live.md): Activate your production account, assign team roles, configure keys and notification URLs, and verify a production order.
- [Account activation and team roles](https://waffo.com/docs/en/developer-docs/getting-started/account-and-roles.md): Activate a Waffo production account, add Dashboard members, and assign roles by responsibility.
- [Configure the merchant public key](https://waffo.com/docs/en/developer-docs/getting-started/public-key-configuration.md): Upload a production merchant public key in Waffo Dashboard, complete the signature challenge, and track its review status.
- [Configure refund and Chargeback notification URLs](https://waffo.com/docs/en/developer-docs/getting-started/notification-url-configuration.md): Configure global refund and Chargeback notification URLs in Waffo Dashboard.

### Core Concepts

- [Payment lifecycle and order statuses](https://waffo.com/docs/en/developer-docs/core-concepts/payment-lifecycle.md): Learn how Waffo payment orders, subscriptions, and refunds transition between statuses.
- [Amounts and currencies](https://waffo.com/docs/en/developer-docs/core-concepts/currency.md): Waffo amount formatting specifications and multi-currency payment guidance.
- [Pricing currency strategy](https://waffo.com/docs/en/developer-docs/use-cases/pricing-currency.md): An overview of the three pricing currency strategies supported by Waffo: global uniform pricing, per-country pricing, and regional pricing, including how to pass the correct parameters.
- [Error Handling](https://waffo.com/docs/en/developer-docs/core-concepts/error-handling.md): A guide to Waffo API error code categories and handling Unknown Status exceptions.
- [Idempotency](https://waffo.com/docs/en/developer-docs/core-concepts/idempotency.md): Use idempotency keys to prevent duplicate charges and ensure payment security.

### Integration

- [Choosing an integration approach](https://waffo.com/docs/en/developer-docs/use-cases/checkout-solution.md): Compare Waffo's two checkout integration modes to choose the right approach.
- [Set up and use Coupons](https://waffo.com/docs/en/developer-docs/use-cases/coupons.md): Enable Coupons, configure Promotion Codes in Merchant Portal, and apply discounts through the API or Waffo Checkout.
- [Tax integration](https://waffo.com/docs/en/developer-docs/use-cases/tax.md)
- [AI integration tool (waffo-integrate)](https://waffo.com/docs/en/developer-docs/integration/ai-integration.md): Automatically complete and verify Waffo SDK integration with AI coding tools.
- [Checkout integration - Integration steps](https://waffo.com/docs/en/developer-docs/integration/checkout/steps.md): The complete process for integrating payments using the Waffo hosted Checkout.
- [Cashier integration - Customization options](https://waffo.com/docs/en/developer-docs/integration/checkout/customization.md): Configurations such as cashier payment method filtering, multi-currency, language, and theme customization.
- [Merchant Portal cashier customization](https://waffo.com/docs/en/developer-docs/integration/checkout/portal-customization.md): Configure cashier Logo, theme styles, sub-merchant styles, publishing rules, and permissions in the Merchant Portal.
- [x402 stablecoin acquiring](https://waffo.com/docs/en/developer-docs/use-cases/x402-stablecoin-acquiring.md): Accept USDC stablecoin payments from AI Agents through the x402 protocol: a complete integration guide covering both merchant-hosted 402 and Waffo-hosted modes.

#### Subscription use cases

- [Add seats and charge the difference](https://waffo.com/docs/en/developer-docs/use-cases/subscription-use-cases.md): Review the key fields for charging a current-period Subscription top-up.

#### Apple Pay integration

- [Apple Pay integration](https://waffo.com/docs/en/developer-docs/integration/apple-pay/overview.md): Compare four Apple Pay integration options and their different requirements for runtime environment, frontend work, and token handling.
- [Direct Apple Pay integration](https://waffo.com/docs/en/developer-docs/integration/apple-pay/merchant-direct-integration.md): Decrypt Apple Pay tokens on your server and pass the decrypted result to Waffo in the required format.

#### API-only integration

- [Overview](https://waffo.com/docs/en/developer-docs/integration/api/overview.md): A manual API integration roadmap for one-time payment and subscription payment.
- [Code examples](https://waffo.com/docs/en/developer-docs/integration/api/examples.md): Multilingual API integration code examples for Node.js, Java, Go, Python, PHP, and raw HTTP.

#### Elements (Frontend SDK)

- [Frontend components - component usage](https://waffo.com/docs/en/developer-docs/integration/elements/usage.md): How to integrate frontend components to embed payment capabilities into merchant pages.
- [Frontend components - Style customization](https://waffo.com/docs/en/developer-docs/integration/elements/styling.md): Customization options for cashier appearance, language, and payment method filtering.

#### Card Binding & Token

- [Waffo Checkout card binding](https://waffo.com/docs/en/developer-docs/integration/tokenization/checkout-card-binding.md): Complete a CIT in Waffo Checkout and create a card token for subsequent MIT payments.
- [Merchant-side card binding](https://waffo.com/docs/en/developer-docs/integration/tokenization/overview.md): Bind a card independently on the merchant page and manage its token for subsequent payments.

#### Subscription integration

- [Subscription integration](https://waffo.com/docs/en/developer-docs/integration/subscription/overview.md): The main path for subscription (recurring billing) integration: from choosing a subscription model through sandbox acceptance.
- [Subscription payment method comparison](https://waffo.com/docs/en/developer-docs/tools-and-references/references/subscription-payment-methods.md): How payment methods differ for subscriptions — renewal management, frequency, trial period, and management.

#### Settlement & Reconciliation

- [Reconciliation reports](https://waffo.com/docs/en/developer-docs/tools-and-references/references/reconciliation-reports.md): Definitions, CSV fields, file naming, and examples for Waffo reconciliation reports.

### Integration - Google Pay

- [Google Pay™](https://waffo.com/docs/en/developer-docs/integration/google-pay/google-pay.md)

### Webhook

- [Webhook - Overview and configuration](https://waffo.com/docs/en/developer-docs/webhook/overview.md): Overview and configuration requirements for Waffo Webhook asynchronous event notifications.
- [Webhook - event type list](https://waffo.com/docs/en/developer-docs/webhook/event-types.md): Detailed descriptions and payload examples for all Waffo Webhook event types.
- [Webhook - signature verification](https://waffo.com/docs/en/developer-docs/webhook/signature-verification.md): RSA signature verification method and code examples for Webhook requests.
- [Webhook - Handling best practices](https://waffo.com/docs/en/developer-docs/webhook/best-practices.md): Best practices for webhook handling: idempotency, fast responses, security, and more.
- [Webhook - retries and failure recovery](https://waffo.com/docs/en/developer-docs/webhook/retry.md): Webhook retry mechanism and failure recovery strategy.

### SDK

- [Node.js SDK](https://waffo.com/docs/en/developer-docs/sdk/nodejs.md): Waffo Node.js SDK installation, initialization, and usage guide.
- [Java SDK](https://waffo.com/docs/en/developer-docs/sdk/java.md): Installation, initialization, and usage guide for the Waffo Java SDK.
- [Go SDK](https://waffo.com/docs/en/developer-docs/sdk/go.md): Waffo Go SDK installation, initialization, and usage guide.
- [Python SDK](https://waffo.com/docs/en/developer-docs/sdk/python.md): Waffo Python SDK installation, initialization, and usage guide.
- [PHP SDK](https://waffo.com/docs/en/developer-docs/sdk/php.md): Waffo PHP SDK installation, initialization, and usage guide.
- [SDK changelog](https://waffo.com/docs/en/developer-docs/sdk/changelog.md): Changelog for Waffo Node.js, Java, Go, Python, and PHP SDK releases.

### Tools & Reference

#### Developer Tools

- [Postman collection](https://waffo.com/docs/en/developer-docs/tools-and-references/developer-tools/postman.md): Use the Postman collection to quickly test the Waffo API.
- [Sandbox simulator](https://waffo.com/docs/en/developer-docs/tools-and-references/developer-tools/sandbox-simulator.md): Instructions for using the simulator in the sandbox environment to simulate various payment scenarios.
- [Octopus sandbox test payment](https://waffo.com/docs/en/developer-docs/tools-and-references/developer-tools/octopus-sandbox-e2e.md): Follow the Octopus test app guide to complete sandbox payment testing.

#### Reference

- [Error code quick reference](https://waffo.com/docs/en/developer-docs/tools-and-references/developer-tools/error-codes.md): A complete list of Waffo API error codes and category descriptions.
- [Data reference](https://waffo.com/docs/en/developer-docs/tools-and-references/references/data-reference.md): A complete reference for Waffo status codes, enums, payment method types, and general conventions.
- [Frequently asked questions (FAQ)](https://waffo.com/docs/en/developer-docs/tools-and-references/references/faq.md): Common questions and answers about Waffo integration, payments, and security.
- [Payment method integration notes](https://waffo.com/docs/en/developer-docs/tools-and-references/references/payment-method-integration-notes.md): Payment method and environment-specific notes for Checkout integrations.
- [Integration acceptance criteria](https://waffo.com/docs/en/developer-docs/tools-and-references/references/acceptance-criteria.md): Acceptance criteria for merchants after completing Waffo integration, covering functional tests, exception handling, parameter requirements, and data integrity.
- [API version history](https://waffo.com/docs/en/developer-docs/tools-and-references/references/changelog.md): Waffo API version history and changelog.

### Point Topup API

- [Point Topup integration overview](https://waffo.com/docs/en/developer-docs/point-topup/overview.md): The three Waffo Point Topup integration modes for suppliers, who provides which endpoint, and the preparation checklist per mode.
- [Mode A: offline point code import](https://waffo.com/docs/en/developer-docs/point-topup/mode-a-offline-import.md): The supplier delivers point codes offline as Excel/CSV, Waffo Point Topup imports them into inventory and handles the sale and delivery. No API development.
- [Mode B: point code retrieval API](https://waffo.com/docs/en/developer-docs/point-topup/mode-b-point-code-api.md): After the user completes payment, Waffo Point Topup calls the supplier's point code retrieval API in real time. Request and response fields, idempotency requirement, and examples.
- [Mode C: direct fulfillment API](https://waffo.com/docs/en/developer-docs/point-topup/mode-c-direct-fulfillment.md): Signed URL redirect, direct fulfillment, fulfillment inquiry, and the fulfillment result webhook. After the user completes payment, Waffo Point Topup calls the supplier's endpoint to credit the user's account directly.
- [Point Topup API common specifications](https://waffo.com/docs/en/developer-docs/point-topup/api-common.md): Interface conventions, message structure, SHA256WithRSA signing and verification, error codes, and RSA key generation for Waffo Point Topup supplier integrations.

## API Reference

### Overview

- [Introduction](https://waffo.com/docs/api-reference/introduction.md): Waffo Acquiring Order API reference

### One-time Payment

- [Create new order](https://waffo.com/docs/api-reference/order-create/create-new-order.md): Note: For certain Pay Methods, some optional fields are required. Kindly refer to Section Specific Pay Method Requirement
- [Order inquiry](https://waffo.com/docs/api-reference/order-inquiry/order-inquiry.md)
- [Order cancel](https://waffo.com/docs/api-reference/order-cancel/order-cancel.md)
- [Order refund](https://waffo.com/docs/api-reference/order-refund/order-refund.md)
- [Refund inquiry](https://waffo.com/docs/api-reference/refund-inquiry/refund-inquiry.md)
- [Order capture](https://waffo.com/docs/api-reference/order-capture/order-capture.md)

### Subscription

- [Create Subscription](https://waffo.com/docs/api-reference/subscription-create/create-subscription.md): Note: For certain Pay Methods, some optional fields are required. Kindly refer to Section Specific Pay Method Requirement
- [Subscription Inquiry](https://waffo.com/docs/api-reference/subscription-inquiry/subscription-inquiry.md)
- [Subscription cancel](https://waffo.com/docs/api-reference/subscription-cancel/subscription-cancel.md)
- [Subscription manage](https://waffo.com/docs/api-reference/subscription-manage/subscription-manage.md)
- [Subscription change](https://waffo.com/docs/api-reference/subscription-change/subscription-change.md)
- [Subscription change inquiry](https://waffo.com/docs/api-reference/subscription-change-inquiry/subscription-change-inquiry.md)
- [Subscription update](https://waffo.com/docs/api-reference/subscription-update/subscription-update.md)
- [Subscription resume](https://waffo.com/docs/api-reference/subscription-resume/subscription-resume.md)

### Configuration

- [Merchant Config inquiry](https://waffo.com/docs/api-reference/merchant-config-inquiry/merchant-config-inquiry.md)
- [Pay Method Config Inquiry](https://waffo.com/docs/api-reference/pay-method-config-inquiry/pay-method-config-inquiry.md)
- [Wallet inquiry](https://waffo.com/docs/api-reference/wallet-inquiry/wallet-inquiry.md): Query on-chain wallet / receiving address (network/asset/payTo) for x402 stablecoin payin

### Chargeback

- [Chargeback inquiry](https://waffo.com/docs/api-reference/chargeback-inquiry/chargeback-inquiry.md): Query a single chargeback by chargebackId or originalOrderId. Note: when the original order has more than one chargeback, for example after escalation to Second Cycle, query by chargebackId.
- [Chargeback list](https://waffo.com/docs/api-reference/chargeback-list/chargeback-list.md): Query chargebacks by creation time range, status and life cycle. Note: this API does not return the message and evidence objects; use Chargeback inquiry to retrieve them.
- [Chargeback accept](https://waffo.com/docs/api-reference/chargeback-accept/chargeback-accept.md): Accept the chargeback. The amount and fee were already debited when the chargeback was created, so accepting does not trigger a further debit — the case is closed and the merchant is not refunded. Note: this action is irreversible — no further evidence can be submitted afterwards, and an ACCEPTED no…
- [Chargeback update](https://waffo.com/docs/api-reference/chargeback-update/chargeback-update.md): Submit defense evidence in First Cycle, or defend the case in Second Cycle. Note: in First Cycle at least one evidence file is required, supplied through message.documents or evidence.othersFile; in Second Cycle the call itself defends the case and evidence is not accepted. On success the status bec…
- [Chargeback file upload](https://waffo.com/docs/api-reference/chargeback-file-upload/chargeback-file-upload.md): Upload an evidence file and obtain the fileId used by the Chargeback update API. Send the request as multipart/form-data. Note: this API is authenticated by X-API-KEY only and does not participate in RSA signing; the response carries no X-SIGNATURE. The merchantId must match the merchant bound to th…
- [Chargeback file download](https://waffo.com/docs/api-reference/chargeback-file-download/chargeback-file-download.md): Download a previously uploaded evidence file. On success the API returns HTTP 302 Found with a Location header pointing to a time-limited pre-signed URL; the file content is served from that URL, so the HTTP client must follow redirects (curl requires -L). This API does not stream the file bytes dir…
- [Reported Fraud list](https://waffo.com/docs/api-reference/reported-fraud-list/reported-fraud-list.md): Query the fraud reports the card schemes raised against your transactions, filtered by fraud report date, card scheme and acquiring order Id.  Reported fraud is the card scheme's own fraud signal and is independent of chargebacks: a reported transaction may never be charged back, and a chargeback ma…

### Tokenization

- [Tokenization Generate](https://waffo.com/docs/api-reference/waffo-tokenization-api/tokenization-generate.md)
- [Tokenization Inquiry](https://waffo.com/docs/api-reference/waffo-tokenization-api/tokenization-inquiry.md)
- [Tokenization remove](https://waffo.com/docs/api-reference/waffo-tokenization-api/tokenization-remove.md)

### Payout

- [Payout create](https://waffo.com/docs/api-reference/payout-create/payout-create.md)
- [Payout inquiry](https://waffo.com/docs/api-reference/payout-inquiry/payout-inquiry.md)

### Point Topup

- [Signed redirect to checkout](https://waffo.com/docs/api-reference/point-topup-redirect/signed-redirect-to-checkout.md): Hands an end user from the supplier's site to the Waffo Point Topup storefront. Waffo validates the required parameters, checks that `timestamp` is within 2 hours, recalculates the signature, issues a session token and then redirects the user to the `siteCode` purchase page.
- [Fulfillment inquiry](https://waffo.com/docs/api-reference/point-topup-fulfillment-inquiry/fulfillment-inquiry.md): Lets the supplier query the fulfillment result of a Mode C order from Waffo Point Topup. This is the pull-based counterpart of the fulfillment event webhook, typically used for reconciliation or when a webhook notification was missed.
- [Fulfillment result webhook](https://waffo.com/docs/api-reference/point-topup-fulfillment-webhook.md): Webhook Waffo Point Topup sends to the supplier's own endpoint with the final fulfillment status of a Mode C order.

## Other

- [Frontend component - Google Pay integration](https://waffo.com/docs/en/developer-docs/integration/elements/frontend-integration.md): A complete guide to integrating Google Pay payments on the merchant page.
- [Stripe Migration Tool](https://waffo.com/docs/en/developer-docs/tools-and-references/references/stripe-adapter.md): Keep your existing Stripe calls and hand expiring subscriptions over to Waffo in three steps.
- [Stripe Migration Tool Integration Guide](https://waffo.com/docs/en/developer-docs/tools-and-references/references/stripe-adapter-integration.md): Integrate the Stripe migration tool into your Java project to move expiring Stripe subscriptions to Waffo and verify inquiry, cancellation, and Sandbox behavior.
- [フロントエンドコンポーネント - Google Pay 連携](https://waffo.com/docs/ja/developer-docs/integration/elements/frontend-integration.md): 加盟店ページに Google Pay 決済を組み込むための完全ガイド。
- [Stripe 移行ツール](https://waffo.com/docs/ja/developer-docs/tools-and-references/references/stripe-adapter.md): 既存の Stripe 呼び出しを維持し、3 ステップで期限が近づいたサブスクリプションを Waffo へ引き継ぎます。
- [Stripe 移行ツール連携ガイド](https://waffo.com/docs/ja/developer-docs/tools-and-references/references/stripe-adapter-integration.md): 有効期限が近づいた Stripe サブスクリプションを Waffo へ移行する手順と、照会、解約、Sandbox 検証を説明します。
- [前端组件 - Google Pay 集成](https://waffo.com/docs/zh/developer-docs/integration/elements/frontend-integration.md): 在商户页面集成 Google Pay 支付的完整指南。
- [Stripe 迁移工具](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/stripe-adapter.md): 保留现有 Stripe 调用，只需 3 步，将即将到期的订阅交接给 Waffo。
- [Stripe 迁移工具接入指南](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/stripe-adapter-integration.md): 把 Stripe 迁移工具接入你的 Java 项目：将即将到期的 Stripe 订阅转移至 Waffo，并完成查询、取消与 Sandbox 验证。

## OpenAPI Specs

- [openapi](/docs/api-reference/openapi.json)
- [tokenization-api](/docs/api-reference/tokenization-api.json)
- [point-topup-api](/docs/api-reference/point-topup-api.json)
- [chargeback-api](/docs/api-reference/chargeback-api.json)

> The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages.

## Indexes

- [English / Guides (121 pages)](https://waffo.com/docs/_llms/en/guides.txt): Documentation for English / Guides.
- [Japanese (211 pages)](https://waffo.com/docs/_llms/ja.txt): Documentation for Japanese.
- [Japanese / ガイド (121 pages)](https://waffo.com/docs/_llms/ja/tab.txt): Documentation for Japanese / ガイド.
- [Chinese (211 pages)](https://waffo.com/docs/_llms/zh.txt): Documentation for Chinese.
- [Chinese / 产品指南 (121 pages)](https://waffo.com/docs/_llms/zh/tab.txt): Documentation for Chinese / 产品指南.


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