Docs menu

Preview: the API is being built and these endpoints may change

POST/api/v1/data

Buy data

Send a data plan to any Nigerian number.

Sends the plan through a line or channel that can send it on its network and answers with the final state.

Body

FieldTypeRequiredNotes
product_codestringyesA plan's product_code from List plans, such as MTN-SHARE-1GB-30D
phone_numberstringyesNigerian number, 08012345678 or +2348012345678. phone is accepted as an alias
client_referencestringnoYour own reference, 1 to 128 characters, unique per mode

Send an Idempotency-Key header with every request. Like airtime, the call waits for the final state; add ?wait=0 to get 202 at once.

Request

bash
curl https://api.simconnectng.com/api/v1/data \
  -H "Authorization: Bearer $SIMCONNECT_KEY" \
  -H "Idempotency-Key: order_1043" \
  -H "Content-Type: application/json" \
  -d '{ "product_code": "MTN-SHARE-1GB-30D", "phone_number": "08012345678", "client_reference": "order_1043" }'

Response

json
{
  "success": true,
  "data": {
    "id": "0192f4c3-b5d2-7e8a-9f1c-6b7d8e9a0f21",
    "reference": "txn_0192f4c3b5d24e8a9f1c6b7d8e9a0f21",
    "client_reference": "order_1043",
    "mode": "live",
    "status": "successful",
    "product_code": "MTN-SHARE-1GB-30D",
    "network": "mtn",
    "service": "data",
    "destination": "+234********78",
    "amount": 350.00,
    "price": 10.00,
    "failure_code": null,
    "failure_message": null,
    "created_at": "2026-10-06T12:06:38Z",
    "completed_at": "2026-10-06T12:06:41Z"
  },
  "message": "Transaction successful",
  "code": "OK"
}

amount is the plan's face value; price is the flat fee your wallet pays for the sale. The figures shown here are placeholders.

Error

A plan that cannot be sold right now is refused before anything is held:

json
{
  "success": false,
  "data": { "errors": [{ "field": "product_code", "message": "This plan is not sellable from lines: no charges are set for it" }] },
  "message": "This plan is not sellable from lines: no charges are set for it",
  "code": "VALIDATION_FAILED"
}

Give this to your coding agent

prompt
Read https://simconnectng.com/docs/api/buy-data.md and implement "Buy data" (POST /api/v1/data) in this project.
Read the API key from the SIMCONNECT_KEY environment variable.
Send an Idempotency-Key derived from our own order id.
Every response is { success, data, message, code }; on an error data is null (or carries data.errors), so branch on code.
View as markdown