> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mode B: point code retrieval API

> 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 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](https://mintcdn.com/waffo-docs/hUiobY-hbNbq3QYe/images/developer-docs/point-topup/mode-b-flow.png?fit=max\&auto=format\&n=hUiobY-hbNbq3QYe\&q=85\&s=f9f91095f4a7831e5eb34c14ed8d31be)

## API list

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

> [!WARNING]
>
> 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](/docs/en/developer-docs/point-topup/mode-c-direct-fulfillment.md#url-signature-and-redirect) from Mode C, or simply provide a direct link without a signature:

```text theme={null}
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](/docs/en/developer-docs/point-topup/api-common.md#api-security) |

> [!WARNING]
>
> **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

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

```json Response (success) theme={null}
{
  "code": "0",
  "msg": "success",
  "data": {
    "distributorOrderId": "WP202501050001",
    "status": "SUCCESS",
    "pointList": [
      {
        "pointCode": "ABCD-1234-EFGH-5678",
        "expiryDate": "2026-12-31",
        "faceValue": "1000"
      }
    ]
  }
}
```

```json Response (failure) theme={null}
{
  "code": "0",
  "msg": "success",
  "data": {
    "distributorOrderId": "WP202501050001",
    "status": "FAILURE",
    "failureCode": "INSUFFICIENT_INVENTORY",
    "failureReason": "No available points in inventory"
  }
}
```

> [!NOTE]
>
> 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](/docs/en/developer-docs/point-topup/api-common.md#error-codes).

## Next steps

> **[API common specifications](/docs/en/developer-docs/point-topup/api-common.md)**
>
> Message structure, RSA signing and verification, error codes, and key generation.

> **[Mode C: direct fulfillment API](/docs/en/developer-docs/point-topup/mode-c-direct-fulfillment.md)**
>
> To credit the user's account directly instead of issuing point codes, see Mode C.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.