Docs menu

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

GET/api/v1/transactions/{reference}

Get a transaction

One sale, its current state and its full timeline.

Returns the sale with every state it moved through, from created to successful or failed, each with a time and a reason.

Request

bash
curl https://api.simconnectng.com/api/v1/transactions/txn_0192f4c1a7e84b6f9d2c3e5a7b9d1f30 \
  -H "Authorization: Bearer $SIMCONNECT_KEY"

Response

json
{
  "success": true,
  "data": {
    "reference": "txn_0192f4c1a7e84b6f9d2c3e5a7b9d1f30",
    "client_reference": "order_1042",
    "status": "successful",
    "product_code": "MTN-VTU",
    "network": "mtn",
    "destination": "+234********78",
    "amount": 500.00,
    "price": 2.00,
    "attempt_count": 1,
    "created_at": "2026-10-06T12:04:01Z",
    "completed_at": "2026-10-06T12:04:03Z",
    "timeline": [
      { "from_status": null, "to_status": "created", "reason": "accepted", "actor_type": "api_key", "candidate_kind": null, "provider": null, "provider_reference": null, "created_at": "2026-10-06T12:04:01.120Z" },
      { "from_status": "created", "to_status": "queued", "reason": "hold placed", "actor_type": "system", "candidate_kind": null, "provider": null, "provider_reference": null, "created_at": "2026-10-06T12:04:01.131Z" },
      { "from_status": "queued", "to_status": "processing", "reason": "executor started", "actor_type": "system", "candidate_kind": null, "provider": null, "provider_reference": null, "created_at": "2026-10-06T12:04:01.348Z" },
      { "from_status": "processing", "to_status": "successful", "reason": "success", "actor_type": "system", "candidate_kind": "sim", "provider": "simgateway", "provider_reference": "8F2K41", "created_at": "2026-10-06T12:04:03.902Z" }
    ]
  },
  "message": "OK",
  "code": "OK"
}

The sale also carries the other fields of Send airtime (id, mode, service, failure_code, failure_message). status can also be refunded, when we refund a sale, and the timeline then gains that step. The figures shown here are placeholders.

Error

json
{ "success": false, "data": null, "message": "Transaction not found", "code": "NOT_FOUND" }

Give this to your coding agent

prompt
Read https://simconnectng.com/docs/api/get-transaction.md and implement "Get a transaction" (GET /api/v1/transactions/{reference}) in this project.
Read the API key from the SIMCONNECT_KEY environment variable.
Every response is { success, data, message, code }; on an error data is null (or carries data.errors), so branch on code.
View as markdown