Bills & VTU
Airtime, data, power, TV and exam PINs — through one API.
Buy for your customers from your prepaid balance: look up what a biller sells, buy it with an idempotency key, and hand your customer what they paid for.
curl https://api.vertexbridge.io/v1/partner/catalogue/electricity \
-H "X-API-Key: $VERTEXBRIDGE_API_KEY"curl https://api.vertexbridge.io/v1/partner/purchases/airtime \
-H "X-API-Key: $VERTEXBRIDGE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "amount_minor": 50000, "customer_reference": "'"$CUSTOMER_PHONE"'",
"your_reference": "order-2207" }'Amounts are integers in kobo. Every product has its own path — /data, /electricity, /cable and /exam_pin beside /airtime. Data, electricity and cable take their codes from the catalogue.
What your customers can buy
Airtime
An amount you choose, to a phone number. No lookup needed.
Data bundles
Bundles for a phone number, chosen from the catalogue.
Electricity
For a meter number. The meter token comes back to you.
Cable TV
Subscription renewals, by smartcard or decoder number.
Exam PINs
An examination PIN, returned to you once.
How it works
Step 1: Look up what to buy
For data, electricity and cable, the catalogue lists who sells it and what they sell. Send the codes back exactly as listed — they are not yours to parse. Airtime needs no lookup.
Step 2: Buy, with an idempotency key
One path per product. Every purchase carries an Idempotency-Key: retry with the same key and you get the original answer back, never a second purchase.
Step 3: Keep what was delivered
A meter token or a PIN comes back in the response, in a replay of it with the same key, and when you look the purchase up — including one that went through after our first answer. Store it when you receive it.
Built for purchases that cannot be undone
A token, a PIN or a top-up is delivered the moment it is bought. These are the properties that matter when something goes wrong.
Indeterminate, not failed
If a biller does not answer clearly, the purchase is indeterminate — it may already have been delivered. Do not retry it and do not refund your customer; we find out, and the answer appears when you look the purchase up by its reference.
Reserved before it is bought
The amount and our fee are held from your prepaid balance before the biller is called. A purchase your balance cannot cover is refused before anything is sent.
Your customer’s details stay out of our logs
Phone, meter and smartcard numbers are not kept with the transaction, and a token or PIN is never written to a log.
Enabled per product
Each of the five is switched on for your account separately, and a key must carry permission to buy before it can.
The integration, step by step, is in the Bills & VTU guide. How retries work is in Idempotency, what an unclear answer means in Indeterminate, and every field and state in the API reference.
Set up bills and VTU for your platform
Each product is enabled per account. Tell us which you need and your volumes, and we will set up your account and agree your rates.