Airtime, Gift Cards & Bills

Sell mobile airtime and data, gift cards, and utility bill payments to your customers through one API. You fund a prepaid balance with stablecoins, set your own margin, and keep everything you charge on top.

Base URL: https://api.rach.finance/api/v1/ · Auth: X-API-Key

One service, three products. Airtime, gift cards and bills share one order model, one status vocabulary, one webhook family and one balance. Look any order up at GET /vas/orders/{reference} regardless of what it was.

How it works

Fund your balance

Send USDT or USDC on Polygon or BSC to your funding address. A flat $1 is deducted and the rest becomes spendable.

Set your margin

Decide what you charge your customers on top. Rach never takes any part of it.

Quote, then sell

Price an order first to see exactly what you earn, then buy. Your balance is charged; your customer pays you whatever you decided.

1. Fund your balance

curl https://api.rach.finance/api/v1/vas/funding-addresses \
  -H "X-API-Key: $RACH_KEY"

Response

{
  "addresses": [
    { "network": "POL", "address": "0xAbC123...", "currencies": ["USDT", "USDC"] },
    { "network": "BSC", "address": "0xAbC123...", "currencies": ["USDT", "USDC"] }
  ],
  "funding_fee_usd": "1"
}

Only USDT or USDC on Polygon or BSC will credit your balance. Any other asset, or any other chain, will not — those funds are not recoverable through this flow.A flat **

1** is deducted per deposit. A deposit that cannot cover the fee is not credited at all, so send more than

Stablecoins credit 1:1 with USD, so there is no exchange-rate gap between what you send and what you can spend. The address is yours permanently — reuse it for every top-up. Nothing needs to be pre-registered, and no memo or tag is required.

When the money becomes spendable

Your balance credits once the deposit reaches its confirmation threshold, not the moment it appears on-chain. We wait so that a chain reorganisation cannot take back funds you have already spent.

Chain	Confirmations	Typical wait
BSC	12	~40 seconds
Polygon	128	~4–5 minutes

Fund on BSC if you want the balance quickly. Polygon’s threshold is deliberately deep because it has had deep reorganisations; BSC settles in well under a minute.

You also receive the usual wallet.deposit.confirmed webhook, so you can credit your own system the moment the balance is live rather than polling. Check the balance any time:

curl https://api.rach.finance/api/v1/vas/balance -H "X-API-Key: $RACH_KEY"

Response

{ "balance": "499.000000", "currency": "USD", "lifetime_funded": "499.000000", "lifetime_spent": "0" }

2. Set your margin

This is what you earn on every order. Rach bills you a price; you charge your customer that price plus your markup, and keep the difference.

curl -X POST https://api.rach.finance/api/v1/vas/markup \
  -H "X-API-Key: $RACH_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_enabled": true, "fee_mode": "percentage", "fee_percent": "0.03", "fee_cap_usd": "5" }'

fee_percent is a fraction, not a percent — "0.03" means 3%. Sending "3" would mean 300%; values above 1 are rejected outright rather than silently overcharging your customers.

Use "fee_mode": "flat" with flat_fee_usd for a fixed charge instead, and applies_to (airtime, giftcard, bill) to set different margins per product.

3. Quote before you sell

A quote shows the whole economics of an order — including what you make — without buying anything or touching your balance.

curl -X POST https://api.rach.finance/api/v1/airtime/quote \
  -H "X-API-Key: $RACH_KEY" -H "Content-Type: application/json" \
  -d '{ "phone": "+2348031234567", "country_code": "NG", "amount": "1000", "use_local_amount": true }'

Response

{
  "quote": {
    "type": "airtime",
    "product_name": "MTN Nigeria",
    "face_value": "1000",
    "face_currency": "NGN",
    "merchant_price": "0.796020",
    "merchant_markup": "0.024881",
    "customer_price": "0.820901",
    "merchant_earns": "0.024881",
    "currency": "USD"
  }
}

Field	Meaning
`face_value`	What the recipient actually receives
`merchant_price`	What Rach charges you — deducted from your balance
`merchant_markup`	Your margin, from the configuration above
`customer_price`	What to charge your customer (`merchant_price` + your markup)
`merchant_earns`	Your profit on this order

4. Sell

Airtime, data and bundles

curl -X POST https://api.rach.finance/api/v1/airtime/topup \
  -H "X-API-Key: $RACH_KEY" -H "Content-Type: application/json" \
  -d '{
    "reference": "order-2026-0001",
    "customer_id": "cust_001",
    "phone": "+2348031234567",
    "country_code": "NG",
    "amount": "1000",
    "use_local_amount": true
  }'

Omit operator_id and we detect the network from the number, so your customer never has to pick it (or pick it wrong). Set use_local_amount: true to send the amount in the recipient’s own currency — usually what they expect to type. Data plans and bundles use the same endpoint. Pick the data product from the operator list and pass its operator_id:

# Data plans only — render these as their own tab
curl "https://api.rach.finance/api/v1/airtime/operators?country=NG&type=data" \
  -H "X-API-Key: $RACH_KEY"

type accepts airtime, data or bundle; omit it for everything. Each entry also carries data and bundle booleans if you would rather group them yourself.

Check for promotions before you sell. Operators run bonuses — “recharge 1974 XAF or more and the receiver gets 100% extra” — which is free upside for your customer on the same spend.

curl "https://api.rach.finance/api/v1/airtime/promotions?country=NG" \
  -H "X-API-Key: $RACH_KEY"

Gift cards

curl -X POST https://api.rach.finance/api/v1/giftcards/orders \
  -H "X-API-Key: $RACH_KEY" -H "Content-Type: application/json" \
  -d '{
    "reference": "gc-2026-0001",
    "product_id": 2,
    "unit_price": "25",
    "recipient_email": "customer@example.com"
  }'

The redeem code is attached to the order on success and returned here and at GET /vas/orders/{reference}.

Redeem codes are never sent in webhooks. A gift card code is a bearer secret — anyone holding it can spend it — so it is only ever returned over an authenticated request.

Utility bills

Browse billers, optionally filtered by category:

# Categories available in a country, for a filter UI
curl "https://api.rach.finance/api/v1/bills/types?country=NG" -H "X-API-Key: $RACH_KEY"

# Billers in one category
curl "https://api.rach.finance/api/v1/bills/billers?country=NG&type=ELECTRICITY_BILL_PAYMENT" \
  -H "X-API-Key: $RACH_KEY"

Then pay — quote first with POST /bills/quote if you want to show a price:

curl -X POST https://api.rach.finance/api/v1/bills/pay \
  -H "X-API-Key: $RACH_KEY" -H "Content-Type: application/json" \
  -d '{
    "reference": "bill-2026-0001",
    "biller_id": 1,
    "subscriber_account": "04220312345",
    "amount": "5000",
    "use_local_amount": true
  }'

Check the meter or account number with your customer before paying. The provider does not validate subscriber accounts, so a payment to a mistyped meter number is delivered to whoever owns that meter and cannot be recalled.

`reference` is your idempotency key

Always send a unique reference, and reuse it on retries. Repeating a POST with the same reference returns the original order instead of buying a second time.This is enforced by a database constraint, not a best-effort check — so retrying after a timeout is always safe. Without it, a network blip means your customer gets charged once and topped up twice.

What happens when something fails

Orders run in a fixed sequence, so a failure is never ambiguous:

The amount is validated against the operator’s real rules (fixed denominations, min/max).
Your balance is debited — if it is too low the order stops here and nothing is spent.
The provider is called.
If the provider fails, your balance is refunded automatically.

Status	Meaning
`successful`	Delivered
`processing`	Accepted, outcome not yet final — Rach settles it in the background
`failed`	Not delivered; your balance was refunded
`refunded`	Delivered then reversed by the provider; your balance was refunded

A processing order resolves on its own within a couple of minutes, and a webhook fires when it does. If a customer is watching the screen, settle it immediately instead:

curl -X POST https://api.rach.finance/api/v1/vas/orders/order-2026-0001/refresh \
  -H "X-API-Key: $RACH_KEY"

You may also see a 503 meaning the service is temporarily unavailable. That is the platform topping up its own provider balance — you were not charged and nothing was attempted. Retry shortly with the same reference.

A 502 means the provider failed, not that your request was wrong — your balance was already returned. A 400 with an insufficient-balance message means nothing was attempted at all; top up and retry with the same reference.

A client timeout is not a failure. Purchases complete and are recorded even if your HTTP client disconnects mid-flight. Never retry with a new reference after a timeout — look the order up by your original reference instead.

Webhooks

Terminal states fire vas.order.successful, vas.order.failed or vas.order.refunded to your configured webhook URL, carrying the order reference, status, amounts and what you were charged. Verify them the same way as every other Rach webhook — see Webhooks.

Dashboard

One call for a merchant dashboard screen: balance, whether you can currently transact, order counts, spend versus earnings, and recent orders.

curl "https://api.rach.finance/api/v1/vas/dashboard?days=30" -H "X-API-Key: $RACH_KEY"

Money figures count successful orders only — failed orders are refunded, so including them would overstate both your spend and your earnings.

More endpoints

Endpoint	Purpose
Airtime & data

Endpoint	Purpose
`GET /airtime/countries`	Countries supported for airtime
`GET /airtime/operators?country=NG`	Networks, data plans and bundles — add `&type=data` to filter
`GET /airtime/detect?phone=…&country=NG`	Detect the network for a number
`GET /airtime/promotions?country=NG`	Operator bonuses you can advertise
`POST /airtime/quote`	Price a top-up and see your margin
`POST /airtime/topup`	Send airtime, data or a bundle

Gift cards

Endpoint	Purpose
`GET /giftcards/countries`	Countries with gift cards available
`GET /giftcards/products?country=US`	Gift cards available to buy
`GET /giftcards/products/{id}`	One product’s full detail, for a product page
`GET /giftcards/redeem-instructions`	What a customer does with a code, per brand
`POST /giftcards/quote`	Price a gift card and see your margin
`POST /giftcards/orders`	Buy a gift card

Utility bills

Endpoint	Purpose
`GET /bills/types?country=NG`	Biller categories, for a filter UI
`GET /bills/billers?country=NG`	Utilities available to pay
`POST /bills/quote`	Price a bill and see your margin
`POST /bills/pay`	Pay a bill

Your account

Endpoint	Purpose
`GET /vas/funding-addresses`	Where to send USDT/USDC to top up
`GET /vas/balance`	Spendable balance
`GET /vas/statement`	Every credit, debit and fee behind your balance
`GET	POST /vas/markup`	Your margin
`GET /vas/dashboard`	Balance, volumes, spend vs earnings, recent orders
`GET /vas/orders`	All your orders, filterable by type and status
`GET /vas/orders/{reference}`	One order (incl. gift card redeem code)
`POST /vas/orders/{reference}/refresh`	Settle a processing order now

Full schemas are in the Payments API Reference under Value-Added Services.

Get Started

Core Products

Monitoring & Webhooks

Airtime, Gift Cards & Bills

How it works

1. Fund your balance

When the money becomes spendable

2. Set your margin

3. Quote before you sell

4. Sell

Airtime, data and bundles

Gift cards

Utility bills

`reference` is your idempotency key

What happens when something fails

Webhooks

Dashboard

More endpoints

​How it works

​1. Fund your balance

​When the money becomes spendable

​2. Set your margin

​3. Quote before you sell

​4. Sell

​Airtime, data and bundles

​Gift cards

​Utility bills

​reference is your idempotency key

​What happens when something fails

​Webhooks

​Dashboard

​More endpoints

How it works

1. Fund your balance

When the money becomes spendable

2. Set your margin

3. Quote before you sell

4. Sell

Airtime, data and bundles

Gift cards

Utility bills

`reference` is your idempotency key

What happens when something fails

Webhooks

Dashboard

More endpoints