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

# Point Topup integration overview

> The three Waffo Point Topup integration modes for suppliers, who provides which endpoint, and the preparation checklist per mode.

**Waffo Point Topup** is Waffo's point-card top-up API and white-label point-card top-up solution. As a **supplier**, you connect your point-code inventory or top-up capability, and Waffo Point Topup runs the end-user-facing side on your behalf: a multi-lingual storefront on a dedicated subdomain, global payment methods, merchant-of-record for the sale, and regular settlement.

These pages cover the technical integration. For the product introduction, see [Point Topup](/docs/en/essentials/point-topup.md).

## Terminology

| Term | Description |
| - | - |
| **Waffo Point Topup** | Waffo's point-card top-up API and white-label point-card top-up solution. Simplifies integration through URL redirection and offers global payment methods on its multi-lingual site, acting as merchant-of-record for selling points or credits. Each supplier integration gets a dedicated subdomain: `https://{supplier}.waffoplay.com/{site_code}/` |
| **Supplier** | The upstream service provider that provides point codes or direct fulfillment services to Waffo Point Topup, for example game publishers and point-code issuers |
| **Distributor** | In this context, Waffo Point Topup acts as the official distributor for the supplier |
| **End user** | The consumer who purchases point codes or top-up services on the Waffo Point Topup platform |

## Three integration modes

| Mode | Name | Description | API required | Best for |
| - | - | - | - | - |
| **A** | Offline point code import | Supplier provides point codes offline, Waffo Point Topup imports them into inventory | No API | Quick launch without API integration |
| **B** | Point code retrieval API | Waffo Point Topup calls the supplier's API to retrieve point codes in real time | Supplier provides API | Point code security and expiration control by the supplier |
| **C** | Direct fulfillment API | Waffo Point Topup calls the supplier's API to top up the user's account directly | Supplier provides API | User experience and conversion rate, with direct fulfillment |

![Decision chart for choosing a Waffo Point Topup integration mode based on the supplier's system setup](https://mintcdn.com/waffo-docs/hUiobY-hbNbq3QYe/images/developer-docs/point-topup/integration-mode-decision.png?fit=max\&auto=format\&n=hUiobY-hbNbq3QYe\&q=85\&s=97a31807d3e13d0dbb2361eb251eb480)

> **[Online demo site](https://waffoplay-demo-01.waffo.dev/)**
>
> To see how the three modes work in practice, walk through the end-to-end flows on the demo site.

### Mode comparison

| Feature | Mode A (offline) | Mode B (point code API) | Mode C (direct fulfillment) |
| - | - | - | - |
| API development | Not required | Required | Required |
| Real-time fulfillment | Yes, to the user's email address | Yes, to the user's email address | Yes, direct fulfillment |
| Inventory management | By Waffo | By supplier | None |
| Integration from supplier to Waffo | Static link to Waffo Point Topup | Static link to Waffo Point Topup | Dynamic link with order parameters and signature |
| Integration from Waffo to supplier | N/A | Supplier's point code retrieval API | Supplier's direct fulfillment API |
| Best for | Quick launch without API integration | Point code security and expiration control by supplier | User experience and conversion rate |

## Who provides which endpoint

Waffo provides only two endpoints and one webhook. They live in the Point Topup group of the [API Reference](/docs/api-reference/introduction.md).

Everything on the supplier side is an **optional integration**: the specifications in this documentation are samples. If you already have equivalent endpoints, hand your own API documentation to Waffo Point Topup and Waffo adapts to your existing interface.

| Endpoint | Provider | Integration |
| - | - | - |
| `GET /redirect` signed redirect | Waffo | **Required** for Mode C |
| `POST /api/v1/gamepin/fulfillment-inquiry` fulfillment inquiry | Waffo | Optional |
| `FULFILLMENT_RESULT_NOTIFY` fulfillment result webhook | Waffo sends, supplier receives | Optional |
| Point code retrieval | Supplier | Optional integration (sample spec) |
| Direct fulfillment | Supplier | Optional integration (sample spec) |
| Fulfillment inquiry | Supplier | Optional integration (sample spec) |

> [!NOTE]
>
> The minimal Mode C integration is the `GET /redirect` 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`.

## Preparation per mode

> **Mode A: offline point code import**
>
> Materials required from the supplier:
>
> | No. | Material | Details | Notes |
> | - | - | - | - |
> | 1 | Point code data file | Excel/CSV format | Follow the Waffo Point Topup template |
> | 2 | SKU information | Product types, face values, currencies | Confirm with Waffo Point Topup |
> | 3 | Settlement info | Bank account, settlement cycle | For settlement |
>
> Integration steps:
>
> **1. Provide point code data**
>
> Supplier provides point code data offline as Excel/CSV.
>
> **2. Import inventory**
>
> Waffo Point Topup imports the point codes into the inventory system.
>
> **3. Receive the purchase link**
>
> Waffo Point Topup provides the purchase link to the supplier.
>
> **4. Embed the link**
>
> Supplier embeds the purchase link on its own website.
>
> **5. Delivery**
>
> After a user purchases, Waffo Point Topup sends the point code to the user's email.
>
> **6. Settlement**
>
> Waffo Point Topup provides periodic settlement reports.
>
> See [Mode A: offline point code import](/docs/en/developer-docs/point-topup/mode-a-offline-import.md).

> **Mode B: point code retrieval API**
>
> Materials required from the supplier:
>
> | No. | Material | Details | Notes |
> | - | - | - | - |
> | 1 | RSA public key | For API signature verification | 2048-bit |
> | 2 | API key | `X-API-KEY` | Supplier provides it to Waffo Point Topup |
> | 3 | API endpoint URL | Point code retrieval API URL | Production and test environments |
> | 4 | SKU information | Product types, face value list | Confirm with Waffo Point Topup |
> | 5 | Distributor ID | `distributorId` | Unique distributor ID assigned by the supplier to Waffo Point Topup |
> | 6 | Settlement info | Bank account, settlement cycle | For settlement |
>
> Integration steps:
>
> **1. Exchange RSA public keys**
>
> Supplier and Waffo Point Topup exchange RSA public keys.
>
> **2. Provide API materials**
>
> Supplier provides the API key and API documentation.
>
> **3. Joint testing**
>
> Test the point code retrieval API together.
>
> **4. Receive the purchase link**
>
> Waffo Point Topup provides the purchase link as a static link.
>
> **5. Embed the link**
>
> Supplier embeds the link on its own website.
>
> **6. Go live**
>
> Launch in production.
>
> See [Mode B: point code retrieval API](/docs/en/developer-docs/point-topup/mode-b-point-code-api.md).

> **Mode C: direct fulfillment API**
>
> Materials required from the supplier:
>
> | No. | Material | Details | Notes |
> | - | - | - | - |
> | 1 | RSA public key | For API signature verification | 2048-bit |
> | 2 | `SECRET_KEY` | For URL signature | For signing redirect links |
> | 3 | API endpoint URLs | Fulfillment API and inquiry API | Production and test environments |
> | 4 | Supplier ID | `supplierId` | Unique supplier ID assigned by Waffo |
> | 5 | Supported site code list | `siteCode` | For example `US`, `JP`, `HK` |
> | 6 | Settlement info | Bank account, settlement cycle | For settlement |
> | 7 | Webhook URL | Fulfillment event notification endpoint | For receiving fulfillment status |
>
> Integration steps:
>
> **1. Exchange RSA public keys**
>
> Supplier and Waffo Point Topup exchange RSA public keys.
>
> **2. Provide keys and materials**
>
> Supplier provides `SECRET_KEY`, the API key, and API documentation.
>
> **3. Implement URL signing**
>
> Supplier implements the URL signature logic on the backend.
>
> **4. Joint testing**
>
> Test URL signature verification, the direct fulfillment API, the inquiry API (optional), and the fulfillment event webhook (optional).
>
> **5. Embed signed redirect links**
>
> Supplier integrates the signed redirect links on its website.
>
> **6. Go live**
>
> Launch in production.
>
> See [Mode C: direct fulfillment API](/docs/en/developer-docs/point-topup/mode-c-direct-fulfillment.md).

## Next steps

> **[Mode A: offline point code import](/docs/en/developer-docs/point-topup/mode-a-offline-import.md)**
>
> Point code CSV format, purchase link embedding, and settlement reports.

> **[Mode B: point code retrieval API](/docs/en/developer-docs/point-topup/mode-b-point-code-api.md)**
>
> Request and response fields plus the idempotency requirement for real-time retrieval.

> **[Mode C: direct fulfillment API](/docs/en/developer-docs/point-topup/mode-c-direct-fulfillment.md)**
>
> Signed URL redirect, direct fulfillment, and fulfillment inquiry.

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


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