# Waffo Documentation

## Guides

### Products and Services

- [Waffo Product Overview](https://waffo.com/docs/en/essentials/product-overview.md): Building global payment infrastructure. A full-stack solution from acquiring to growth.

### Acquiring & Payments

- [Checkout](https://waffo.com/docs/en/essentials/checkout.md): Waffo's standardized checkout product for managing global payment interaction flows across one-time and subscription payment modes.
- [One-time Payment](https://waffo.com/docs/en/essentials/one-time-payment.md): One integration, global payment methods covered — every transaction clear and in control.
- [Subscription & Recurring](https://waffo.com/docs/en/essentials/subscription-recurring.md): Providing automated, high-success-rate billing solutions for recurring payment scenarios. Through a mechanism of one-time authorization and multiple automated deductions, we support flexible billing cycle configurations and smart retries.
- [Payment Methods](https://waffo.com/docs/en/essentials/payment-methods.md): Connect your business to mainstream global and distinctive local payment methods through a single, unified API interface.

### Settlement & Funds

- [Merchant Settlement](https://waffo.com/docs/en/essentials/merchant-settlement.md): Intelligent and transparent global fund settlement service that automatically converts multi-currency transactions and optimizes merchants' cash flow via flexible settlement strategies.
- [Merchant Portal](https://waffo.com/docs/en/essentials/merchant-portal.md): A one-stop payment management platform for cross-border enterprises. Manage transactions, settlements, analytics, and team access in one place.

### Value-Added Services

- [Dispute and Chargeback](https://waffo.com/docs/en/essentials/dispute-chargeback.md): A systematic, tiered closed-loop defense system covering three core stages: Chargeback Alert, Customer Dispute, and Chargeback.
- [Data Intelligence](https://waffo.com/docs/en/essentials/data-intelligence.md): End-to-end data intelligence that translates obscure bank codes into actionable growth strategies.

### Advanced Features

- [Tokenization](https://waffo.com/docs/en/essentials/tokenization.md): Securely store payment credentials using Waffo Tokens to enable one-click checkout, recurring billing, and delayed charges without handling raw card numbers.
- [Auth-Capture](https://waffo.com/docs/en/essentials/auth-capture.md): Split payments into two steps — authorize funds upfront and capture them only when the transaction is confirmed, reducing fraud risk and refund costs.

### Point Topup

- [Point Topup](https://waffo.com/docs/en/essentials/point-topup.md): Waffo Point Topup is a point-card top-up API and white-label point-card top-up solution. Suppliers connect their point-code inventory or top-up capability through an API or a single URL redirect, with no storefront or payment work of their own.

## 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.
- [Go-live checklist](https://waffo.com/docs/en/developer-docs/getting-started/go-live.md): A complete checklist before switching from the sandbox to the production environment.

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

- [Card binding and token management](https://waffo.com/docs/en/developer-docs/integration/tokenization/overview.md): Securely convert users’ bank card information into a token so future payments don’t require entering the card number again.

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

### 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.
- [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 — billing model, frequency, trial period, and management.
- [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)

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

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

- [Japanese (95 pages)](https://waffo.com/docs/_llms/ja.md): Documentation for Japanese.
- [Chinese (95 pages)](https://waffo.com/docs/_llms/zh.md): Documentation for Chinese.