Mode B: point code retrieval API

Mode B is for suppliers that already run a point inventory system with API capability. After the user completes payment, Waffo Point Topup calls your API to retrieve point codes in real time.

Advantages

Real-time point code retrieval
No manual inventory management
Automatic inventory sync

Use cases

Game publishers with a digital point generation system
Point code distributors with an existing API

Integration flow

Mode B point code retrieval flow: after payment, Waffo calls the supplier endpoint for a code in real time and emails it to the user

API list

No.	API name	Description	Provider	Integration
1	Point code retrieval	Real-time point code retrieval	Supplier	Optional integration (sample spec)

The specification on this page is a sample. If you already have a point code retrieval endpoint, hand your own API documentation to Waffo Point Topup — Waffo Point Topup adapts to your existing interface, so there is no need to rebuild it to match this page.

User redirection

To send users from your own website to Waffo Point Topup, you can use the URL signature method from Mode C, or simply provide a direct link without a signature:

https://{supplier}.waffoplay.com/{site_code}/

Point code retrieval endpoint

Called by Waffo Point Topup after the user completes payment, to retrieve point codes from the supplier.

Item	Value
Method	`POST`
Path	Defined by the supplier
Authentication	Common API signature (SHA256WithRSA), see API common specifications

Idempotency requirement: the supplier must support idempotency on distributorOrderId + distributorId. If the same request arrives more than once, return the same point codes and do not deduct inventory again.

Request

Field name	Description	Type	Required
`distributorId`	The distributor ID assigned to Waffo Point Topup by the supplier	String(64)	required
`distributorOrderId`	Waffo Point Topup’s order ID. Used with `distributorId` as the idempotent key	String(64)	required
`skuId`	SKU identifier	String(128)	required
`quantity`	Number of points to retrieve, usually 1	Integer	required
`faceValue`	Face value, for dynamic value products	String(32)	optional
`requestedAt`	Waffo Point Topup-side request time	String(32)	required

Response

Field name		Description	Type	Required
`distributorOrderId`		Waffo Point Topup’s order ID	String(64)	required
`status`		Order status: `SUCCESS` point retrieved successfully, `FAILURE` retrieval failed	String(24)	required
`pointList`		List of point codes, returned only when `status` is `SUCCESS`	Array	optional
	`pointCode`	Point code	String(128)	required
	`expiryDate`	Expiration date	String(32)	optional
	`faceValue`	Face value	String(32)	optional
`failureCode`		Failure code, returned when `status` is `FAILURE`	String(24)	optional
`failureReason`		Failure reason	String(128)	optional

Examples

{
  "distributorId": "WAFFO_POINT_TOPUP_001",
  "distributorOrderId": "WP202501050001",
  "skuId": "SUPPLIER_POINT_001",
  "quantity": 1,
  "faceValue": "1000",
  "requestedAt": "2025-01-05T10:30:00.000Z"
}

{
  "code": "0",
  "msg": "success",
  "data": {
    "distributorOrderId": "WP202501050001",
    "status": "SUCCESS",
    "pointList": [
      {
        "pointCode": "ABCD-1234-EFGH-5678",
        "expiryDate": "2026-12-31",
        "faceValue": "1000"
      }
    ]
  }
}

{
  "code": "0",
  "msg": "success",
  "data": {
    "distributorOrderId": "WP202501050001",
    "status": "FAILURE",
    "failureCode": "INSUFFICIENT_INVENTORY",
    "failureReason": "No available points in inventory"
  }
}

A status of FAILURE is a business failure: the HTTP status code and the outer code still report success. Return system-level errors per the error codes.

Next steps

API common specifications

Message structure, RSA signing and verification, error codes, and key generation.

Mode C: direct fulfillment API

To credit the user’s account directly instead of issuing point codes, see Mode C.

Getting Started

Core Concepts

Integration

Webhook

SDK

Tools & Reference

Point Topup API

Advantages

Use cases

Integration flow

API list

User redirection

Point code retrieval endpoint

Request

Response

Examples

Next steps

API common specifications

Mode C: direct fulfillment API

Advantages

Use cases

​Integration flow

​API list

​User redirection

​Point code retrieval endpoint

​Request

​Response

​Examples

​Next steps

API common specifications

Mode C: direct fulfillment API

Integration flow

API list

User redirection

Point code retrieval endpoint

Request

Response

Examples

Next steps