> ## 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.

<CardGroup cols={2}>
  <Card title="Advantages" icon="circle-check">
    * Real-time point code retrieval
    * No manual inventory management
    * Automatic inventory sync
  </Card>

  <Card title="Use cases" icon="users">
    * Game publishers with a digital point generation system
    * Point code distributors with an existing API
  </Card>
</CardGroup>

## Integration flow

<Frame>
  <img src="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" alt="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" width="2653" height="1584" data-path="images/developer-docs/point-topup/mode-b-flow.png" />
</Frame>

## 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.
</Warning>

## 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#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#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.
</Warning>

### 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

<CodeGroup>
  ```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"
    }
  }
  ```
</CodeGroup>

<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#error-codes).
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="API common specifications" icon="shield-check" href="/docs/en/developer-docs/point-topup/api-common">
    Message structure, RSA signing and verification, error codes, and key generation.
  </Card>

  <Card title="Mode C: direct fulfillment API" icon="zap" href="/docs/en/developer-docs/point-topup/mode-c-direct-fulfillment">
    To credit the user's account directly instead of issuing point codes, see Mode C.
  </Card>
</CardGroup>