API Reference · v1

Reteller API

A single REST API for airtime, data, cable TV, electricity, betting, international top-ups, gift cards and travel eSIMs. All requests and responses are JSON, authenticated with your API keys, and every call returns the same response envelope. Failed orders are reversed to your wallet automatically.

Base URL https://reteller.net/api/v1
Format JSON
Auth API key (public + secret)
Currency NGN

Create API keys

In Settings → API keys. You receive a public and a secret key.

Fund your wallet

Every sale is charged to your Reteller wallet balance.

Make a request

Verify with GET /ping, then transact with POST /purchase.

Contents

Authentication

Every request must include your public and secret keys. Choose one of two schemes — both are equivalent.

Authorization header (recommended)

Authorization: Bearer PUBLIC_KEY:SECRET_KEY

Discrete headers

X-Public-Key: PUBLIC_KEY
X-Secret-Key: SECRET_KEY

Keys are created and revoked in Settings → API keys. Keep the secret key server-side; never expose it in client code. All endpoints are relative to the base URL:

base url

https://reteller.net/api/v1

Response format

Responses share one envelope. On success, status is true and the result is in data. On failure, status is false with a human-readable message, and data is null.

envelope

{
  "status": true,        // false on error
  "message": "…",       // human-readable summary
  "data": { … }          // result, or null on error
}

Endpoint index

All v1 endpoints at a glance.

Method	Endpoint	Description
GET	/ping	Verify API keys
GET	/balance	Wallet balance
GET	/services	Full catalogue
GET	/products/{category}	Products in a category
POST	/purchase	Buy airtime, data, cable, power…
GET	/transactions/{reference}	Retrieve a transaction
GET	/airtime/operators	International airtime operators
POST	/airtime/purchase	Send airtime abroad
GET	/data/operators	International data operators
POST	/data/purchase	Send data abroad
GET	/giftcards	Gift-card products
POST	/giftcards/purchase	Buy a gift card
GET	/esim/packages	eSIM plans for a destination
POST	/esim/purchase	Buy an eSIM
GET	/esim/status/{reference}	Retrieve an eSIM profile

GET/ping

Confirms your API keys are valid. Does not touch your wallet.

request

curl https://reteller.net/api/v1/ping \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

GET/balance

Returns your current wallet balance.

request

curl https://reteller.net/api/v1/balance -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

response

{ "status": true, "data": { "wallet_balance": 15000.00, "currency": "NGN" } }

GET/services

Returns the full catalogue as categories → products → variations. Use a variation's code as the variation_code when creating a purchase.

response

{ "status": true, "data": [
  { "code": "data-gifting", "service_type": "data", "products": [
    { "code": "data-gifting-mtn", "network": "MTN", "variations": [
      { "code": "mtn-1gb-30", "price": 600, "data_value": "1GB" }
    ] } ] } ] }

GET/products/{category}

Returns the products in a single category.

Path parameters

Parameter	Type		Description
`category`	string	required	Category code, e.g. `airtime`, `data-gifting`, `cable`, `electricity`, `betting`.

request

curl https://reteller.net/api/v1/products/airtime -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

POST/purchaseCore

Creates a purchase for any local service. Manual-amount services (airtime, electricity, betting) also require amount.

Body parameters

Parameter	Type		Description
`variation_code`	string	required	The variation to buy, from `/services`.
`recipient`	string	required	Phone, smartcard, meter or customer ID for the service.
`amount`	number	optional	Required for manual-amount services (airtime, electricity, betting).
`meter_type`	string	optional	Electricity only — `prepaid` or `postpaid`.
`subscription_type`	string	optional	Cable only — `change` or `renew`.

request

curl -X POST https://reteller.net/api/v1/purchase \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variation_code": "mtn-1gb-30", "recipient": "08012345678" }'

response

{ "status": true, "message": "Transaction successful.", "data": {
  "reference": "RT240717ABC123", "status": "successful",
  "amount": 600, "wallet_balance": 14400.00 } }

GET/transactions/{reference}

Retrieves a transaction by reference. Use it to resolve orders that returned pending.

Path parameters

Parameter	Type		Description
`reference`	string	required	The `reference` returned when the transaction was created.

request

curl https://reteller.net/api/v1/transactions/RT240717ABC123 \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

International airtime

Top up mobile numbers in 150+ countries. Airtime is priced live per country, so list operators first, then buy. Each operator is either FIXED (choose an options[] entry and send its sender value) or RANGE (send any amount between range.min and range.max). The ngn field is what your wallet is charged.

Opaque tokens: the id and code values here (and for data, gift cards and eSIMs) are opaque — send them back exactly as received; do not parse or construct them.

GET/airtime/operators

Query parameters

Parameter	Type		Description
`country`	string	required	ISO-3166 alpha-2 country code, e.g. `US`, `GB`, `GH`.

request

curl "https://reteller.net/api/v1/airtime/operators?country=US" \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

response

{ "status": true, "data": {
  "country": "US", "operators": [
    { "id": "~mJ8x2", "name": "AT&T USA", "currency": "USD",
      "denominationType": "RANGE",
      "range": { "min": 5, "max": 100, "ngnMin": 8400, "ngnMax": 168000 },
      "options": [] } ] } }

POST/airtime/purchase

Body parameters

Parameter	Type		Description
`operator_id`	string	required	Operator `id` from `/airtime/operators`.
`amount`	number	required	A FIXED option's `sender` value, or any value within the RANGE.
`phone`	string	required	Recipient number in international format, e.g. `+14155550123`.
`country`	string	required	ISO alpha-2 country code.

request

curl -X POST https://reteller.net/api/v1/airtime/purchase \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operator_id": "~mJ8x2", "amount": 10,
        "phone": "+14155550123", "country": "US" }'

A pending status settles shortly — poll /transactions/{reference} to confirm.

International data

Data bundles for numbers abroad, using the same live list-then-buy model as airtime. Operators return real bundle sizes in their options[] labels.

GET/data/operators

Query parameters

Parameter	Type		Description
`country`	string	required	ISO alpha-2 country code.

response

{ "status": true, "data": {
  "country": "US", "operators": [
    { "id": "~kQ2pR", "name": "T-Mobile Data USA", "currency": "USD",
      "denominationType": "FIXED",
      "options": [ { "sender": 10, "ngn": 16800, "label": "3GB - 30 days" } ] } ] } }

POST/data/purchase

Body parameters

Parameter	Type		Description
`operator_id`	string	required	Operator `id` from `/data/operators`.
`amount`	number	required	The chosen option's `sender` value.
`phone`	string	required	Recipient number in international format.
`country`	string	required	ISO alpha-2 country code.

request

curl -X POST https://reteller.net/api/v1/data/purchase \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operator_id": "~kQ2pR", "amount": 10,
        "phone": "+14155550123", "country": "US" }'

Gift cards

Sell branded gift cards priced live per country. The card is delivered by email to the recipient.

GET/giftcards

Query parameters

Parameter	Type		Description
`country`	string	required	ISO alpha-2 country code.

response

{ "status": true, "data": {
  "country": "US", "products": [
    { "id": "~7ZgT", "name": "Amazon US", "brand": "Amazon",
      "denominationType": "FIXED",
      "options": [ { "sender": 25, "ngn": 42000 } ] } ] } }

POST/giftcards/purchase

Body parameters

Parameter	Type		Description
`product_id`	string	required	Product `id` from `/giftcards`.
`amount`	number	required	A FIXED `sender` value, or a value within the RANGE.
`recipient_email`	string	required	Where the gift-card code is sent.

request

curl -X POST https://reteller.net/api/v1/giftcards/purchase \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "product_id": "~7ZgT", "amount": 25,
        "recipient_email": "friend@example.com" }'

Travel eSIMs

Global travel-data eSIMs, priced live in NGN. The flow is three steps: list plans for a destination, buy one, then fetch its QR / activation profile. Ordering is asynchronous — if the profile isn't ready, the eSIM returns PROCESSING; poll the status endpoint for it.

GET/esim/packages

Query parameters

Parameter	Type		Description
`region`	string	required	ISO alpha-2 country code (`US`, `GB`), `!GL` for a global plan, or a region code.

response

{ "status": true, "data": {
  "region": "US", "packages": [
    { "code": "~ifv-1qVTi6TN", "name": "USA 1GB 7 Days",
      "data": "1GB", "days": 7, "ngn": 2500.00 } ] } }

POST/esim/purchase

Body parameters

Parameter	Type		Description
`package_code`	string	required	The `code` from `/esim/packages`.
`email`	string	required	Customer email — the QR / receipt is sent here.

response

{ "status": true, "message": "eSIM ordered — view the QR to install.", "data": {
  "reference": "RT240717ESIM01", "status": "successful", "amount": 2500,
  "esim": {
    "plan": "USA 1GB 7 Days", "iccid": "8910300000...",
    "activation_code": "LPA:1$smdp.io$MATCHING-ID",
    "qr_image": "https://.../qr.png", "smdp": "smdp.io",
    "status": "GOT_RESOURCE" },
  "wallet_balance": 11900.00 } }

To install: scan qr_image, or enter activation_code manually (Settings → Add eSIM).

GET/esim/status/{reference}

Re-fetches the QR / activation profile — use it when a purchase returned status: PROCESSING.

request

curl https://reteller.net/api/v1/esim/status/RT240717ESIM01 \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

Statuses & errors

The status field on a transaction is one of:

Status	Meaning
successful	Delivered to the recipient.
pending	Accepted and settling — re-check with `/transactions/{reference}`.
reversed	Failed and automatically refunded to your wallet.

HTTP status codes

Code	Meaning
`200` / `201`	Success.
`401`	Missing or invalid API keys.
`402`	Insufficient wallet balance.
`404`	Resource not found.
`422`	Validation error — see `message`.
`429`	Too many requests — retry after a short delay.
`502`	Upstream provider unavailable — safe to retry.