Integration guide

Choose an integration path

Choose one path before you start. Both paths end with sandbox testing and submitting acceptance materials to the Waffo technical support group.

API integration

Use this path if you already have your own checkout, need full server-side control, or want to integrate manually with the API Reference.

Choose the payment product

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

Integrate the required APIs

Follow the API direct roadmap and implement the required APIs.

Check API Reference details

Use API Reference for fields, requests, responses, and signing details.

Complete extra payment setup

If you need Apple Pay or Google Pay, complete the extra testing and configuration in Sandbox and testing.

Submit acceptance results

Finish sandbox testing, download and fill in the acceptance case template, then submit the results to the Waffo technical support group.

AI integration tool

Use this path if you want an AI coding tool to generate SDK integration code, tests, and a test report.

Install waffo-integrate

Run npx @waffo/waffo-integrate.

Trigger the integration

Trigger Waffo integration in Claude Code or Cursor.

Answer business questions

Answer the AI’s business questions, such as product type, refund, subscription, and whether Webhook integration is required.

Review code and test report

The AI generates code, runs integration tests, and outputs a test report.

Submit the test report

Submit the test report to the Waffo technical support group for confirmation.

Recommended: Use the AI integration tool (waffo-integrate)

waffo-integrate is Waffo’s official AI integration Skill. It uses an interactive wizard to automatically generate production-ready code — 33% faster than manual integration, with a 100% success rate.

Installation

npx @waffo/waffo-integrate

npx @waffo/waffo-integrate --claude

npx @waffo/waffo-integrate --cursor

Usage

After installation, trigger it in your AI assistant:

Type integrate waffo
The Skill will guide you through: selecting a feature (payment / refund / subscription / Webhook) → detecting your language → generating code → running validation tests

Supported languages and features

Language	SDK	Frameworks
Node.js	`@waffo/waffo-node`	Express, NestJS, Fastify
Java	`com.waffo:waffo-java`	Spring Boot
Go	`github.com/waffo-com/waffo-go/v2`	Gin, Echo, Fiber, Chi

All features can be integrated automatically via the Skill: payments, refunds, subscriptions (including upgrades and downgrades), Webhooks, merchant config queries, and payment method queries.

Advantages

Metric	Using the Skill	Manual integration
Pass rate	100% (16/16 assertions)	75% (12/16)
Integration time	~128 seconds	~192 seconds
13 built-in API rules	Auto error prevention (field names, enum values, required fields)	Must consult docs manually

For full documentation, see waffo-integrate on GitHub.

Manual integration

If you prefer not to use an AI tool, follow these steps to integrate manually.

Prerequisites

Waffo Merchant account
API Key (from the Dashboard)
RSA key pair (see Authentication and signing)

Install the SDK

npm install @waffo/waffo-node

<dependency>
    <groupId>com.waffo</groupId>
    <artifactId>waffo-java</artifactId>
    <version>3.0.0</version>
</dependency>

go get github.com/waffo-com/waffo-go/v2

Initialize the client

import { Waffo, Environment } from '@waffo/waffo-node';

const waffo = new Waffo({
  apiKey: process.env.WAFFO_API_KEY,
  privateKey: process.env.WAFFO_PRIVATE_KEY,
  waffoPublicKey: process.env.WAFFO_PUBLIC_KEY,
  merchantId: process.env.WAFFO_MERCHANT_ID,
  environment: Environment.SANDBOX,
});

import com.waffo.Waffo;
import com.waffo.types.config.WaffoConfig;
import com.waffo.types.config.Environment;

WaffoConfig config = WaffoConfig.builder()
    .apiKey(System.getenv("WAFFO_API_KEY"))
    .privateKey(System.getenv("WAFFO_PRIVATE_KEY"))
    .waffoPublicKey(System.getenv("WAFFO_PUBLIC_KEY"))
    .merchantId(System.getenv("WAFFO_MERCHANT_ID"))
    .environment(Environment.SANDBOX)
    .build();

Waffo waffo = new Waffo(config);

import (
    waffo "github.com/waffo-com/waffo-go/v2"
    "github.com/waffo-com/waffo-go/v2/config"
)

cfg, _ := config.NewConfigBuilder().
    APIKey(os.Getenv("WAFFO_API_KEY")).
    PrivateKey(os.Getenv("WAFFO_PRIVATE_KEY")).
    WaffoPublicKey(os.Getenv("WAFFO_PUBLIC_KEY")).
    MerchantID(os.Getenv("WAFFO_MERCHANT_ID")).
    Environment(config.Sandbox).
    Build()

client := waffo.New(cfg)

Create a payment

import { randomUUID } from 'crypto';

const paymentRequestId = randomUUID().replace(/-/g, '');

const response = await waffo.order().create({
  paymentRequestId,
  merchantOrderId: `ORDER_${Date.now()}`,
  orderCurrency: 'HKD',
  orderAmount: '100.00',
  orderDescription: 'Test Payment',
  notifyUrl: 'https://your-site.com/webhook/waffo',
  userInfo: {
    userId: 'user_123',
    userEmail: 'user@example.com',
    userTerminal: 'WEB',
  },
  paymentInfo: { productName: 'ONE_TIME_PAYMENT' },
  goodsInfo: { goodsUrl: 'https://your-site.com/product/001' },
});

if (response.isSuccess()) {
  const data = response.getData();
  // Redirect the user to the Waffo checkout page
  redirect(data.orderAction);
}

Handle the Webhook callback

See the Webhook section.

Getting Started

Core Concepts

Integration

Webhook

SDK

Tools & Reference

Choose an integration path

API integration

AI integration tool

Recommended: Use the AI integration tool (waffo-integrate)

Installation

Usage

Supported languages and features

Advantages

Manual integration

Prerequisites

Next steps

​Choose an integration path

​API integration

​AI integration tool

​Recommended: Use the AI integration tool (waffo-integrate)

​Installation

​Usage

​Supported languages and features

​Advantages

​Manual integration

​Prerequisites

​Next steps

Choose an integration path

API integration

AI integration tool

Recommended: Use the AI integration tool (waffo-integrate)

Installation

Usage

Supported languages and features

Advantages

Manual integration

Prerequisites

Next steps