Introduction

Welcome to Kaybs Topup API documentation.

Kaybs Topup API provides a high-performance, secure, and reliable interface to integrate digital top-up products into your own platform. Currently we only support Games & Games Vouchers.

Whether you’re building a reseller app, an e-commerce platform, or a corporate rewards system, our API allows you to programmatically fetch products, place orders, and track balances.

Features

  • Blazing Fast: Sub-50ms order ingestion latency.
  • Atomic Operations: We’re ensuring 100% idempotency and zero race conditions for order so you can protect your balance from being deducted twice.
  • Webhook Callbacks: Asynchronous fulfillment with automatic retries on failures.

Prerequisites

Before making any API calls, you must complete the following steps:

IP Whitelist Required

All API endpoints require your server’s IP address to be whitelisted. You must configure at least one IP address in your member dashboard under Developer Settings before making any request. Until you do, every request is rejected with a 403 IP_NOT_WHITELISTED error.

  1. Register: Create an account in the member dashboard: https://[kaybs-domain]/member/register.
  2. Approval: Contact us to have your account upgraded to a reseller and assigned a tier (Bronze, Silver, or Gold). Reseller access is granted by our team — there is no self-service upgrade.
  3. Generate your API Key: Once upgraded, open Developer Settings in your member dashboard and generate your API key. It is the one credential you need: it authenticates every request and signs the callbacks we send you.
  4. Whitelist Your IP: Add your server’s static IP address under Developer Settings > IP Whitelist.

Important

Anyone holding your API key can place orders from your whitelisted IPs. Keep it on your server — never in a URL, a log or client-side code. You can view it again in Developer Settings, and regenerating it revokes the old key (within 60 seconds at most). See Authentication.

API Endpoints Overview

Method Endpoint Description
GET /api/v1/categories List all game categories with input form schemas
GET /api/v1/products Get available products with tier-specific pricing
POST /api/v1/order Place a new top-up order
GET /api/v1/order-status Check the status of a single order
GET /api/v1/orders Paginated order history with filters
GET /api/v1/balance Check your current balance
GET /api/v1/wallet-history Paginated wallet transaction ledger

Base URL

All endpoints are served from a single production base URL:

  • Production API URL: https://[kaybs-domain]/api/v1

Quick Start (cURL)

Check your balance. Every request needs only your API key in the X-Api-Key header:

curl -s https://[kaybs-domain]/api/v1/balance \
  -H "X-Api-Key: 9fQ2xLm7RkT4wVb8NcZ1hJd6YsP3gAe0Ku5Hn2BqXo7MtW9rCv4ElSi1Fy8DpGz3"

Replace the example key with your own (in real code, load it from an environment variable).

Test before going live

You can rehearse your whole integration without spending anything:

  1. GET /api/v1/balance — proves your API key and IP whitelist.
  2. POST /api/v1/order with "test": true — proves ordering and your callback signature check. Nothing is stored and no balance is deducted.
  3. POST /api/v1/order with "test": "failed" — proves your failure handling.
  4. Go live — send the same order without test.

See Test orders for the details.

Postman Collection

For quick testing, download our ready-to-use Postman Collection. Set API_KEY once in the collection variables and every request sends it as X-Api-Key.

Download Postman Collection (kaybs-postman.json)

NextAuthentication