> ## 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).
## 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 |
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).
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) |
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
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:
Supplier provides point code data offline as Excel/CSV.
Waffo Point Topup imports the point codes into the inventory system.
Waffo Point Topup provides the purchase link to the supplier.
Supplier embeds the purchase link on its own website.
After a user purchases, Waffo Point Topup sends the point code to the user's email.
Waffo Point Topup provides periodic settlement reports.
See [Mode A: offline point code import](/docs/en/developer-docs/point-topup/mode-a-offline-import).
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:
Supplier and Waffo Point Topup exchange RSA public keys.
Supplier provides the API key and API documentation.
Test the point code retrieval API together.
Waffo Point Topup provides the purchase link as a static link.
Supplier embeds the link on its own website.
Launch in production.
See [Mode B: point code retrieval API](/docs/en/developer-docs/point-topup/mode-b-point-code-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:
Supplier and Waffo Point Topup exchange RSA public keys.
Supplier provides `SECRET_KEY`, the API key, and API documentation.
Supplier implements the URL signature logic on the backend.
Test URL signature verification, the direct fulfillment API, the inquiry API (optional), and the fulfillment event webhook (optional).
Supplier integrates the signed redirect links on its website.
Launch in production.
See [Mode C: direct fulfillment API](/docs/en/developer-docs/point-topup/mode-c-direct-fulfillment).
## Next steps
Point code CSV format, purchase link embedding, and settlement reports.
Request and response fields plus the idempotency requirement for real-time retrieval.
Signed URL redirect, direct fulfillment, and fulfillment inquiry.
Message structure, RSA signing and verification, error codes, and key generation.