Overview

API integration is suitable when you need full control over the payment flow. You call the Waffo REST API directly and connect payment, subscription, refund, and Webhook handling to your own system.

Applicable scenarios

Server-to-server payment processing
You already have your own hosted checkout page or payment form
Custom integration requiring maximum flexibility

Integration roadmap

Choose the product

Choose one-time payment for single-charge orders, or subscription payment for recurring billing.

Integrate required APIs

One-time payment requires order create, order inquiry, and payment notification. Subscription requires subscription create, subscription inquiry, subscription status notification, and subscription payment notification.

Add conditional APIs as needed

Add cancel, refund, refund inquiry, refund notification, subscription manage, or subscription change only when your business flow needs them.

Use API Reference for field details

Request fields, response fields, enums, and signing rules are maintained in API Reference. Do not copy field definitions from offline PDFs.

Test in sandbox

Use Sandbox and testing, including Apple Pay and Google Pay checks if needed.

Submit acceptance materials

For your first integration, download the one-time payment acceptance template or subscription acceptance template. Only for a subsequent one-time payment integration, download the one-time payment additional integration acceptance template. Fill in the executed cases and submit the result to the Waffo technical support group.

Base URL

Environment	URL
Sandbox	`https://api-sandbox.waffo.com`
Production	`https://api.waffo.com`

Request format

Content-Type: application/json (UTF-8 encoding)
All requests use HTTP POST
Request headers must include X-API-KEY and X-SIGNATURE
Raw HTTP requests must explicitly send X-API-VERSION: 1.0.0. SDKs manage this header automatically; do not set or override it. The v1.3 value in API version history identifies documentation and external contract revisions and must not be used as this request header
subscriptionManagementUrl is required for every /api/v1/subscription/create request

Response format

{
  "code": "0",
  "msg": "Success",
  "data": { ... }
}

code is "0" indicates success
On failure, code is an error code (for example "A0003"), and data is empty
Response header X-SIGNATURE contains the Waffo signature and must be verified

Core APIs

One-time payment

API	Required	Description
`POST /api/v1/order/create`	Required	Create a one-time payment order
`POST /api/v1/order/inquiry`	Required	Query order status, including redirect loss, timeout, and Unknown Status recovery
Payment order notification	Required	Receive terminal payment results and update the merchant order state
`POST /api/v1/order/cancel`	Conditional	Cancel unpaid orders when your business supports cancellation
`POST /api/v1/order/refund`	Conditional	Initiate refunds when your business supports refunds
`POST /api/v1/refund/inquiry` or refund notification	Conditional	Query or receive refund processing results
`POST /api/v1/order/capture`	Conditional	Required only for Auth-Capture manual capture mode

Subscription payment

API	Required	Description
`POST /api/v1/subscription/create`	Required	Create a subscription
`POST /api/v1/subscription/inquiry`	Required	Query subscription status and main payment information
Subscription status notification	Required	Receive subscription activation, cancellation, and status changes
Subscription payment order notification	Required	Receive first-payment and renewal payment results
`POST /api/v1/subscription/cancel`	Conditional	Cancel subscriptions from the merchant side
`POST /api/v1/subscription/manage`	Conditional	Generate a management URL for user-side subscription management
`POST /api/v1/subscription/change`	Conditional	Support plan upgrades or downgrades
`POST /api/v1/order/inquiry`	Conditional	Query detailed failure reasons for subscription payment orders

Configuration lookup

API	Required	Description
`POST /api/v1/merchantconfig/inquiry`	Recommended	Query merchant limits and configuration
`POST /api/v1/paymethodconfig/inquiry`	Recommended	Query available payment methods and payment limits

Acceptance templates

After API integration and sandbox testing, choose the template for your integration stage:

First one-time payment integration: One-time payment acceptance template
First subscription payment integration: Subscription acceptance template
Subsequent one-time payment integration: One-time payment additional integration acceptance template

This template applies to ONE_TIME_PAYMENT. Use it only after you have completed at least one integration acceptance and the current integration is not your first. Do not use it for your first integration.

Submit the completed acceptance result to the Waffo technical support group. See Integration acceptance criteria before going live.

Getting Started

Core Concepts

Integration

Webhook

SDK

Tools & Reference

Point Topup API

Applicable scenarios

Integration roadmap

Base URL

Request format

Response format

Core APIs

One-time payment

Subscription payment

Configuration lookup

Acceptance templates

​Applicable scenarios

​Integration roadmap

​Base URL

​Request format

​Response format

​Core APIs

​One-time payment

​Subscription payment

​Configuration lookup

​Acceptance templates

Applicable scenarios

Integration roadmap

Base URL

Request format

Response format

Core APIs

One-time payment

Subscription payment

Configuration lookup

Acceptance templates