Mode C: direct fulfillment API

Mode C is for suppliers that can credit user accounts directly. After the user completes payment, Waffo Point Topup calls your API to fulfill the top-up, and the user never handles a point code.

Advantages

Seamless user experience, no point code needed
Instant account credit
Higher conversion rate

Use cases

Game publishers with an account top-up system
Membership and subscription services

Integration flow

Simple flow
Detailed flow

Mode C simple flow: the supplier builds a signed redirect link, the user pays on Waffo, and Waffo calls the supplier's fulfillment endpoint

API list

No.	API name	Description	Provider	Integration
1	URL signature and redirect	URL signature authentication	Waffo	required
2	Direct fulfillment	Create a direct fulfillment order	Supplier	Optional integration (sample spec)
3	Fulfillment inquiry	Query a direct fulfillment order. Not needed if your top-up request is itself idempotent — Waffo retries with the same order ID and you guarantee idempotency	Supplier	Optional integration (sample spec)
4	Fulfillment result webhook	Waffo pushes the final fulfillment status to the supplier	Waffo sends	Optional
5	Waffo fulfillment inquiry API	Supplier pulls the fulfillment result from Waffo	Waffo	Optional

The minimal integration needs only items 1 and 4: signed redirect plus the fulfillment result webhook, with no fulfillment endpoint of your own. In that case the webhook only reports PAY_SUCCESS and PAYMENT_FAILED, and you run your own delivery process after receiving PAY_SUCCESS.

URL signature and redirect

Passes user information through signed URL parameters, guaranteeing parameter integrity. This is a Waffo-provided endpoint. The full parameter list with types, requirement flags, and examples is in the API Reference: signed redirect. This section covers how to compute the signature.

The signature must be generated on the supplier backend. Never expose SECRET_KEY to the front end. Signature validity is controlled by timestamp; requests older than 2 hours are rejected.

URL format:

https://{supplier}.waffoplay.com/redirect?amount={amount}&currency={currency}&faceValue={faceValue}&notifyUrl={notifyUrl}&productId={productId}&returnUrl={returnUrl}&salesOrderId={salesOrderId}&siteCode={siteCode}&supplierId={supplierId}&supplierUserAccount={supplierUserAccount}&theme={theme}&timestamp={timestamp}&signature={signature}

{supplier} is the dedicated subdomain Waffo assigns to you during onboarding.

A custom supplier-owned domain can be used instead, as long as you point that domain at the Waffo endpoint. When you do, the base URL in the signing string must be that custom domain — the signature covers the base URL, so a domain mismatch fails verification.

Signature algorithm

Drop parameters

Exclude the signature parameter and drop any parameter whose value is empty or blank.

Sort

Sort the remaining parameters by key in ASCII ascending order.

Build the signing string

Build it as {baseUrl}?key1=value1&key2=value2&.... The base URL — scheme + host + path, for example https://supplier.waffoplay.com/redirect — must be included.

Calculate the signature

Compute HMAC-SHA256 over the signing string, using the shared SECRET_KEY as the HMAC key.

Convert to uppercase

Hex-encode and convert to uppercase.

Signature example

Given these parameters:

Parameter	Value
`supplierUserAccount`	`supplier_user_12345`
`supplierUserEmail`	`test@supplier.com`
`supplierId`	`WAFFO_POINT_TOPUP_001`
`faceValue`	`3000`
`amount`	`3000`
`currency`	`JPY`
`salesOrderId`	`A123456`
`siteCode`	`US`
`returnUrl`	`https://example.com/return_url_page?salesOrderId=XXX`
`theme`	`light`
`timestamp`	`1713483091000`
`SECRET_KEY`	`your_secret_key_here`

Step 1, sort and concatenate:

https://supplier.waffoplay.com/redirect?amount=3000&currency=JPY&faceValue=3000&returnUrl=https://example.com/return_url_page?salesOrderId=XXX&salesOrderId=A123456&siteCode=US&supplierId=WAFFO_POINT_TOPUP_001&supplierUserAccount=supplier_user_12345&supplierUserEmail=test@supplier.com&theme=light&timestamp=1713483091000

Step 2, calculate HMAC-SHA256 and convert to uppercase:

signature = HMAC_SHA256(signing string).toUpperCase()

Complete URL:

https://supplier.waffoplay.com/redirect?amount=3000&currency=JPY&faceValue=3000&returnUrl=https%3A%2F%2Fexample.com%2Freturn_url_page%3FsalesOrderId%3DXXX&salesOrderId=A123456&siteCode=US&supplierId=WAFFO_POINT_TOPUP_001&supplierUserAccount=supplier_user_12345&supplierUserEmail=test@supplier.com&theme=light&timestamp=1713483091000&signature=ABC123XYZ456DEF789

Note that returnUrl appears unencoded in the signing string but URL-encoded in the final URL. Signing and transport are separate steps; do not mix the two forms.

Java implementation example

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.TreeMap;

public class SignatureUtil {

    private static final String HMAC_SHA256 = "HmacSHA256";

    /**
     * Generate signature using HMAC-SHA256 algorithm (including base URL)
     *
     * @param baseUrl   base URL including host and path (e.g., https://supplier.waffoplay.com/redirect)
     * @param params    request parameters
     * @param secretKey secret key
     * @return signature string (uppercase hexadecimal)
     */
    public static String generateSignature(String baseUrl, Map<String, String> params, String secretKey) {
        try {
            // Use TreeMap for automatic alphabetical sorting
            TreeMap<String, String> sortedParams = new TreeMap<>(params);

            // Remove existing signature parameter if present
            sortedParams.remove("signature");

            // Build full URL with sorted parameters
            StringBuilder fullUrl = new StringBuilder(baseUrl);
            fullUrl.append("?");
            for (Map.Entry<String, String> entry : sortedParams.entrySet()) {
                if (fullUrl.charAt(fullUrl.length() - 1) != '?') {
                    fullUrl.append("&");
                }
                fullUrl.append(entry.getKey())
                       .append("=")
                       .append(entry.getValue());
            }

            // Calculate signature using HMAC-SHA256 algorithm
            Mac mac = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKeySpec = new SecretKeySpec(
                secretKey.getBytes(StandardCharsets.UTF_8),
                HMAC_SHA256
            );
            mac.init(secretKeySpec);
            byte[] hash = mac.doFinal(fullUrl.toString().getBytes(StandardCharsets.UTF_8));

            // Convert to hexadecimal string and uppercase
            StringBuilder hexString = new StringBuilder();
            for (byte b : hash) {
                String hex = Integer.toHexString(0xff & b);
                if (hex.length() == 1) {
                    hexString.append('0');
                }
                hexString.append(hex);
            }

            return hexString.toString().toUpperCase();
        } catch (Exception e) {
            throw new RuntimeException("Failed to generate HMAC-SHA256 signature", e);
        }
    }

    /**
     * Verify signature
     */
    public static boolean verifySignature(String baseUrl, Map<String, String> params, String secretKey) {
        String receivedSignature = params.get("signature");
        if (receivedSignature == null || receivedSignature.isEmpty()) {
            return false;
        }
        String calculatedSignature = generateSignature(baseUrl, params, secretKey);
        return calculatedSignature.equals(receivedSignature);
    }

    /**
     * Build the final signed URL
     */
    public static String buildSignedUrl(String baseUrl, Map<String, String> params, String secretKey) {
        TreeMap<String, String> sortedParams = new TreeMap<>(params);
        sortedParams.remove("signature");

        String signature = generateSignature(baseUrl, sortedParams, secretKey);
        sortedParams.put("signature", signature);

        StringBuilder url = new StringBuilder(baseUrl);
        url.append("?");
        for (Map.Entry<String, String> entry : sortedParams.entrySet()) {
            if (url.charAt(url.length() - 1) != '?') {
                url.append("&");
            }
            url.append(entry.getKey())
               .append("=")
               .append(entry.getValue());
        }

        return url.toString();
    }
}

Node.js signing guide (HMAC-SHA256 and RSA-SHA256)

Download Waffoplay Sign Methods.zip for Node.js implementations of HMAC-SHA256 and RSA-SHA256 signing.

Verification flow

When the user accesses the signed URL, the Waffo Point Topup backend:

Receives all URL parameters
Validates that all required parameters are present: faceValue, salesOrderId, supplierId, supplierUserAccount, siteCode, timestamp, signature
Verifies that timestamp is within the valid period of 2 hours
Recalculates the signature using the same algorithm
Compares the calculated signature with the signature in the request
On success, generates a JWT token and sets it in the user session
Redirects to the target siteCode purchase page

Error handling:

Condition	Result
Missing parameters	Redirect to an error page indicating the missing required parameters
Signature verification fails	Redirect to an error page indicating an invalid signature
Timestamp expired	Redirect to an expiry page indicating the link has expired

Direct fulfillment

Called by Waffo Point Topup after the user completes payment.

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

The specification in this section is a sample. If you already have a direct top-up endpoint, hand your own API documentation to Waffo Point Topup — Waffo Point Topup adapts to your existing interface.

Idempotency requirement: the supplier must support idempotency on salesOrderId + supplierId. If the same request arrives more than once, return the same success response.

Strongly recommended: verify that faceValue, amount, and currency for the same salesOrderId are strictly consistent with the order record in your internal system. If that business validation fails, reject the fulfillment.

Request

Field name		Description	Type	Required
`supplierId`		Unique identifier assigned by Waffo to the supplier	String(64)	required
`salesOrderId`		Your order ID provided in the signed URL. Used with `supplierId` as the idempotent key	String(64)	required
`faceValue`		Face value	String(32)	required
`amount`		Actual amount to be paid for the order. If you receive both face value and order amount, validating them against each other is recommended	DECIMAL(20,8)	optional
`currency`		Order pricing currency	String(3)	optional
`requestedAt`		Waffo-side request time. ISO 8601 extended format in UTC, `YYYY-MM-DDThh:mm:ss.sssZ`	String(32)	required
`buyerInfo`		Buyer information. Required in direct fulfillment scenarios	Object	optional
	`supplierUserAccount`	Charge account ID	String(64)	optional

In requestedAt, T separates the date from the time, .000 is milliseconds, and Z denotes UTC. For example 2025-01-05T10:30:00.000Z is 10:30:00 UTC on 5 January 2025.

Response

Field name	Description	Type	Required
`salesOrderId`	Your order ID provided in the signed URL	String(32)	required
`status`	Order status: `IN_PROGRESS` purchase in progress, `SUCCESS` purchase successful, `FAILURE` purchase failed	String(24)	required

Response example:

{
  "code": "0",
  "msg": "success",
  "data": {
    "salesOrderId": "M202504160311311156635",
    "status": "IN_PROGRESS"
  }
}

Fulfillment inquiry

Called by Waffo Point Topup to query the fulfillment result from the supplier.

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

If your direct fulfillment endpoint is itself idempotent, you do not need this inquiry endpoint — Waffo retries with the same salesOrderId and you guarantee idempotent handling.

Request

Field name	Description	Type	Required
`salesOrderId`	Your order ID provided in the signed URL	String(64)	required
`supplierId`	Unique identifier assigned by Waffo to the supplier	String(64)	required

Response

Field name	Description	Type	Required
`salesOrderId`	Your order ID provided in the signed URL	String(64)	required
`supplierId`	Unique identifier assigned by Waffo to the supplier	String(64)	required
`status`	Order status: `IN_PROGRESS`, `SUCCESS`, `FAILURE`	String(24)	required
`faceValue`	Face value. Needed for game point code products with a dynamic value	String(32)	optional
`buyerInfo`	Buyer information, same object structure as the fulfillment request	Object	optional
`requestedAt`	Waffo-side request time, same as the fulfillment request	String(32)	required
`completedTime`	Order completion time	String(32)	optional
`failureCode`	The order’s failure code	String(32)	optional
`failureReason`	The order’s failure reason	String(64)	optional

Response example:

{
  "code": "0",
  "msg": "success",
  "data": {
    "salesOrderId": "M202504160311311156635",
    "supplierId": "123",
    "status": "SUCCESS",
    "faceValue": 1000,
    "buyerInfo": {
      "supplierUserAccount": "user@example.com"
    },
    "requestedAt": "2024-04-16T03:11:31.000Z",
    "completedTime": "2024-04-16T03:12:31.000Z"
  }
}

Fulfillment result webhook

Waffo Point Topup posts the final fulfillment status to the endpoint you pass as the notifyUrl parameter on the signed redirect, covering payment success with fulfillment failure, payment failure, and unpaid orders that timed out. The full field list, the complete failureCode table, and request examples are in the API Reference: fulfillment result webhook.

Idempotency requirement: the supplier must support idempotency on salesOrderId + supplierId. If the same notification arrives more than once, return the same success response.

fulfillmentStatus is what drives your integration logic:

Value	Meaning
`SUCCESS`	Fulfillment successful
`PAY_SUCCESS`	Payment successful. Sent to suppliers without a fulfillment API integration, as the trigger for their own delivery process
`PAY_SUCCESS_SUPPLY_FAILED`	Payment was successful but fulfillment failed. Confirmation required for refund or reissue
`PAYMENT_FAILED`	Payment failed, including user payment timeouts

If you choose the minimal integration — signed redirect plus this webhook, with no fulfillment endpoint — Waffo only reports PAY_SUCCESS and PAYMENT_FAILED.

Response and retry policy

After receiving the fulfillment callback, if you processed it successfully, respond with HTTP 200 OK and include success in the response body. Waffo Point Topup then treats the fulfillment result as successfully notified. Otherwise Waffo Point Topup retries.

{
    "message": "success"
}

Item	Value
Retry intervals	5s, 30s, 1min, 5min, 30min, 1h, 2h, 4h, 8h, 24h, 24h…
Maximum retry attempts	15
After the maximum	The notification is marked as failed and requires manual handling

Waffo fulfillment inquiry API

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 result webhook, typically used for reconciliation or as a fallback when a webhook notification was missed. The response data structure is identical to the webhook data. Full parameters, response examples, and a live playground are in the API Reference: fulfillment inquiry.

Item	Value
Method	`POST`
Path	`/api/v1/gamepin/fulfillment-inquiry`
Authentication	Common API signature (SHA256WithRSA), see API common specifications

Lookup keys: supplierId is required, and at least one of salesOrderId and payOrderId must be provided. If the order does not exist, or does not belong to the calling supplier, an error response is returned per the error codes.

{
    "supplierId": "WAFFO_POINT_TOPUP_001",
    "salesOrderId": "A123456"
}

Next steps

API common specifications

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

Integration overview

Full mode comparison and the preparation checklist.

Getting Started

Core Concepts

Integration

Webhook

SDK

Tools & Reference

Point Topup API

Advantages

Use cases

Integration flow

API list

URL signature and redirect

Signature algorithm

Signature example

Java implementation example

Node.js signing guide (HMAC-SHA256 and RSA-SHA256)

Verification flow

Direct fulfillment

Request

Response

Fulfillment inquiry

Request

Response

Fulfillment result webhook

Response and retry policy

Waffo fulfillment inquiry API

Next steps

API common specifications

Integration overview

Advantages

Use cases

​Integration flow

​API list

​URL signature and redirect

​Signature algorithm

​Signature example

​Java implementation example

Node.js signing guide (HMAC-SHA256 and RSA-SHA256)

​Verification flow

​Direct fulfillment

​Request

​Response

​Fulfillment inquiry

​Request

​Response

​Fulfillment result webhook

​Response and retry policy

​Waffo fulfillment inquiry API

​Next steps

API common specifications

Integration overview

Integration flow

API list

URL signature and redirect

Signature algorithm

Signature example

Java implementation example

Verification flow

Direct fulfillment

Request

Response

Fulfillment inquiry

Request

Response

Fulfillment result webhook

Response and retry policy

Waffo fulfillment inquiry API

Next steps