Getting started
This walks through a first airtime payment. You need:
- an API key (starts with
vmk_live_). Create one under Developers → API keys in the dashboard; - the base URL, from Vmonie;
- money in your wallet (see Funding your wallet).
export VMONIE_API_URL="https://…" # the base URL Vmonie gave you
export VMONIE_API_KEY="vmk_live_…"
1. Check your wallet
curl "$VMONIE_API_URL/api/v1/business/v1/wallet" \
-H "Authorization: Bearer $VMONIE_API_KEY"
{ "balanceMinor": "5000000", "currency": "NGN" }
That is ₦50,000.00.
2. Find the biller
curl "$VMONIE_API_URL/api/v1/business/v1/bills/billers?type=AIRTIME" \
-H "Authorization: Bearer $VMONIE_API_KEY"
[
{ "id": "…", "type": "AIRTIME", "name": "MTN", "isFixedAmount": false },
{ "id": "…", "type": "AIRTIME", "name": "Airtel", "isFixedAmount": false }
]
Use the id as billerId from here on. Billers rarely change, so you can
cache this list for a few hours.
3. Price it (optional)
curl -X POST "$VMONIE_API_URL/api/v1/business/v1/bills/quote" \
-H "Authorization: Bearer $VMONIE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "AIRTIME", "billerId": "<MTN id>", "amountMinor": "100000" }'
{
"amountMinor": "100000",
"feeMinor": "0",
"discountMinor": "0",
"totalMinor": "100000",
"currency": "NGN"
}
totalMinor is what your wallet will be charged.
4. Pay
Send an Idempotency-Key that is unique to this payment. If the request
times out, send it again with the same key: you get the original payment
back and are never charged twice.
curl -X POST "$VMONIE_API_URL/api/v1/business/v1/bills" \
-H "Authorization: Bearer $VMONIE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-10023-airtime" \
-d '{
"type": "AIRTIME",
"billerId": "<MTN id>",
"customerIdentifier": "08031234567",
"amountMinor": "100000"
}'
{
"reference": "VMB…",
"idempotencyKey": "order-10023-airtime",
"status": "SUCCESSFUL",
"type": "AIRTIME",
"billerName": "MTN",
"customerIdentifier": "08031234567",
"amountMinor": "100000",
"feeMinor": "0",
"discountMinor": "0",
"totalMinor": "100000",
"token": null,
"failureReason": null,
"createdAt": "2026-11-16T12:00:00.000Z",
"completedAt": "2026-11-16T12:00:01.000Z"
}
The status is SUCCESSFUL, FAILED, or PENDING while the biller
confirms. Paying bills covers each case.
Next
- Set up webhooks, so you learn about pending payments without polling.
- Read Going live before real traffic.