Buy data

POST 
/api/v1/data

Purchase a data plan for a phone number. The plan's price is debited from your wallet atomically — if delivery fails, you are not charged.

Pass a unique clientReference per purchase: re-sending the same one returns the original transaction instead of buying again, so a timeout is always safe to retry.

Request

Responses

200

The purchase was accepted. status is Success, Failed, or Processing.

Response Headers

Idempotent-Replay

Present and set to true only when this response is an idempotent replay — i.e. the clientReference already had a transaction, so the original is returned unchanged (no new vend, no charge). Absent on a fresh purchase.

401

Missing or invalid API key.

403

This service is not enabled for your account (e.g. airtime is disabled), or the plan is not in your catalog.

409

The clientReference was already used for a different order (a different plan, recipient, or amount). We reject the reuse instead of replaying the unrelated original — no purchase is made and your wallet is not debited. Use a unique clientReference per order; a genuine retry with the same parameters returns the original transaction (see Idempotency).

422

The request body failed validation, or your wallet has insufficient funds.