Buy a bundle
const url = 'https://api.poweredbyaura.com/v1/purchases';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"reference":"order-10293","phone_number":"+2348000000001","bundle_id":"bnd_ng_a_1gb_1d","metadata":{"customer_id":"cus_88412"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.poweredbyaura.com/v1/purchases \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "reference": "order-10293", "phone_number": "+2348000000001", "bundle_id": "bnd_ng_a_1gb_1d", "metadata": { "customer_id": "cus_88412" } }'Buys a bundle for a phone number. The response is the purchase in its current state, which is usually
pending. Follow it to a final state with a webhook or by looking it up.
reference is your own unique ID for the purchase and makes the request safe to retry. Sending the same
reference with the same body returns the original purchase with status 200 and the header
Aura-Idempotent-Replay: true, and never buys twice. Sending it with a different body returns
409 reference_conflict.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Your unique ID for this purchase. Letters, numbers, -, _, . and :, up to 64 characters.
The number to credit, in E.164 format.
Optional. If you send it, Aura checks the number is on this network and refuses the purchase with
network_mismatch if not. If you leave it out, Aura uses the bundle’s network after looking the number
up.
Up to 20 keys of your own, returned on the purchase and in webhooks. Values are strings of up to 500 characters.
object
Examples
Buy 1GB for a customer
{ "reference": "order-10293", "phone_number": "+2348000000001", "bundle_id": "bnd_ng_a_1gb_1d", "metadata": { "customer_id": "cus_88412" }}Responses
Section titled “Responses”A purchase with this reference and the same body already exists. It is returned unchanged.
object
pending: accepted, waiting for the network’s confirmation. successful: the network confirmed the
bundle was credited, and you were charged. failed: the bundle was not credited, and you were not
charged. reversed: the network reversed a successful bundle, and you were refunded. successful,
failed and reversed are final, except that successful can become reversed.
The bundle as it was when bought.
object
The amount held while pending, charged if successful, and refunded if reversed.
object
Amount in the currency’s minor unit (kobo for NGN).
ISO 4217 currency code.
The latest time by which this purchase will reach a final state. If the network has not confirmed by
then, the purchase fails with network_timeout and nothing is charged.
When the purchase reached successful or failed.
Present once the network has confirmed the bundle was credited.
object
The network’s own reference for the credit, when the network provides one.
Present when the purchase failed.
object
Why a purchase failed. New codes may be added in v1.
Present when a successful purchase was reversed.
object
object
Examples
Confirmed by the network
{ "id": "pur_01JA7ZK3Q9W2D8M5X4N6B1C0VE", "object": "purchase", "reference": "order-10293", "status": "successful", "phone_number": "+2348000000001", "network_id": "net_ng_a", "bundle": { "id": "bnd_ng_a_1gb_1d", "name": "1GB Daily", "data_mb": 1024, "validity_hours": 24 }, "price": { "amount": 35000, "currency": "NGN" }, "created_at": "2026-10-12T09:14:30Z", "resolve_by": "2026-10-12T09:44:30Z", "completed_at": "2026-10-12T09:14:31Z", "delivery": { "confirmed_at": "2026-10-12T09:14:31Z", "network_reference": "A-8841207731" }, "failure": null, "reversal": null, "metadata": { "customer_id": "cus_88412" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
Always true on a replayed response.
The purchase was accepted. Its status is usually pending.
object
pending: accepted, waiting for the network’s confirmation. successful: the network confirmed the
bundle was credited, and you were charged. failed: the bundle was not credited, and you were not
charged. reversed: the network reversed a successful bundle, and you were refunded. successful,
failed and reversed are final, except that successful can become reversed.
The bundle as it was when bought.
object
The amount held while pending, charged if successful, and refunded if reversed.
object
Amount in the currency’s minor unit (kobo for NGN).
ISO 4217 currency code.
The latest time by which this purchase will reach a final state. If the network has not confirmed by
then, the purchase fails with network_timeout and nothing is charged.
When the purchase reached successful or failed.
Present once the network has confirmed the bundle was credited.
object
The network’s own reference for the credit, when the network provides one.
Present when the purchase failed.
object
Why a purchase failed. New codes may be added in v1.
Present when a successful purchase was reversed.
object
object
Examples
Accepted, waiting for the network
{ "id": "pur_01JA7ZK3Q9W2D8M5X4N6B1C0VE", "object": "purchase", "reference": "order-10293", "status": "pending", "phone_number": "+2348000000001", "network_id": "net_ng_a", "bundle": { "id": "bnd_ng_a_1gb_1d", "name": "1GB Daily", "data_mb": 1024, "validity_hours": 24 }, "price": { "amount": 35000, "currency": "NGN" }, "created_at": "2026-10-12T09:14:30Z", "resolve_by": "2026-10-12T09:44:30Z", "completed_at": null, "delivery": null, "failure": null, "reversal": null, "metadata": { "customer_id": "cus_88412" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
The request is malformed or a field is invalid. Fix it before retrying.
object
object
A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP
status and retryable flag.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing purchase or the network’s status.
object
Examples
{ "error": { "code": "invalid_phone_number", "message": "phone_number must be in E.164 format, such as +2348000000001.", "param": "phone_number", "retryable": false, "request_id": "req_9Qd4Hs1XvB7n" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
The API key is missing, wrong or revoked.
object
object
A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP
status and retryable flag.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing purchase or the network’s status.
object
Examples
{ "error": { "code": "invalid_api_key", "message": "The API key is not valid.", "retryable": false, "request_id": "req_2Mz6Rt8KcW1p" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
Your balance does not cover this purchase. Nothing was bought.
object
object
A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP
status and retryable flag.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing purchase or the network’s status.
object
Examples
{ "error": { "code": "insufficient_balance", "message": "Your available balance is lower than the price of this bundle.", "retryable": false, "request_id": "req_7Kp2Vx9QmR4t" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
The key is valid but this request is not allowed, for example from an IP address outside your allowlist.
object
object
A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP
status and retryable flag.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing purchase or the network’s status.
object
Examples
{ "error": { "code": "ip_not_allowed", "message": "Requests from 203.0.113.24 are not on your account's allowlist.", "retryable": false, "request_id": "req_5Tg1Nq7JpL3x" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
A purchase with this reference exists with a different body. Nothing was bought.
object
object
A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP
status and retryable flag.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing purchase or the network’s status.
object
Examples
{ "error": { "code": "reference_conflict", "message": "A purchase with reference 'order-10293' already exists with a different phone_number.", "retryable": false, "request_id": "req_3Fh8Lw2NcY6d", "details": { "purchase_id": "pur_01JA7ZK3Q9W2D8M5X4N6B1C0VE" } }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
The request is well formed but cannot be carried out. Nothing was bought.
object
object
A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP
status and retryable flag.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing purchase or the network’s status.
object
Examples
{ "error": { "code": "bundle_unavailable", "message": "Bundle bnd_ng_a_10gb_30d cannot be bought right now.", "param": "bundle_id", "retryable": false, "request_id": "req_4Np9Kx2ZsD6v" }}{ "error": { "code": "network_mismatch", "message": "+2348000000007 is on net_ng_b, but bundle bnd_ng_a_1gb_1d is for net_ng_a.", "param": "bundle_id", "retryable": false, "request_id": "req_1Hb7Vc4MtQ9r", "details": { "detected_network_id": "net_ng_b" } }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
Too many requests. Wait for Retry-After seconds, then retry.
object
object
A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP
status and retryable flag.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing purchase or the network’s status.
object
Examples
{ "error": { "code": "rate_limited", "message": "Too many requests. Retry after 2 seconds.", "retryable": true, "request_id": "req_6Yf2Pk8GwN4s" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
Seconds to wait before retrying.
Requests allowed in the current window.
Requests left in the current window.
Seconds until the current window resets.
Something went wrong on Aura’s side. Retry with the same reference; it will never buy twice.
object
object
A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP
status and retryable flag.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing purchase or the network’s status.
object
Examples
{ "error": { "code": "internal_error", "message": "Something went wrong on our side. Retry with the same reference.", "retryable": true, "request_id": "req_3Js8Bd1RxK7m" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
The network cannot take purchases right now. The error carries its live status. Nothing was bought.
object
object
A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP
status and retryable flag.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing purchase or the network’s status.
object
Examples
{ "error": { "code": "network_unavailable", "message": "net_ng_a is not accepting purchases right now.", "retryable": true, "request_id": "req_7Cv5Gm2TzP8h", "details": { "network": { "id": "net_ng_a", "status": "unavailable", "status_message": "The network is not confirming purchases. We are working with it.", "status_updated_at": "2026-10-12T09:02:00Z" } } }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact your technical contact.
Seconds to wait before retrying.
© 2026 Aura Mobile Communications Ltd ·poweredbyaura.com ·Privacy ·Terms