Airtime Topup

Use this endpoint to purchase airtime for a recipient mobile number.

Flow

Endpoint

POST /airtime/purchase

Headers

Header	Required	Description
X-API-Key	Yes	Partner API key.
X-Timestamp	Yes	ISO timestamp used in signature verification.
X-Signature	Yes	Base64 Ed25519 signature for the request.
Idempotency-Key	Yes	Unique retry-safe operation key.
User-Agent	No	Optional client identifier.

Request Body

Field	Type	Required	Rules
msisdn	string	Yes	Max 32 chars. Example: +251911234567.
amount	number	Yes	Minimum 0.01.
originatingCountry	string	Yes	Sender country (code or name), max 255 chars. Example: US.
foreignCurrencyAmount	number	Yes	Sending amount in USD, must be greater than 0.
exchangeRate	number	Yes	USD to ETB exchange rate, must be greater than 0.

Example Request

curl -X POST "$API_BASE_URL/airtime/purchase" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PARTNER_API_KEY" \
  -H "X-Timestamp: 2026-04-29T12:00:00.000Z" \
  -H "X-Signature: $PARTNER_SIGNATURE" \
  -H "Idempotency-Key: 8c9b3f8d-0f1a-4c6a-8e69-0f6c0a1e39c2" \
  -d '{
    "msisdn": "+251911234567",
    "amount": 100,
    "originatingCountry": "US",
    "foreignCurrencyAmount": 1.77,
    "exchangeRate": 56.5
  }'

{
  "msisdn": "+251911234567",
  "amount": 100,
  "originatingCountry": "US",
  "foreignCurrencyAmount": 1.77,
  "exchangeRate": 56.5
}

Example Response

{
  "id": 98421,
  "correlationId": "airtime_01HWJ7S8E4Y9G7E4F6N5Q2P3Z8",
  "recipientPhone": "+251911234567",
  "amountEtb": 100,
  "transactionStatus": "COMPLETED",
  "telebirrRef": "TB-240427-000123",
  "message": "Airtime purchase completed successfully."
}

transactionStatus can be:

• COMPLETED
• FINALIZATION_PENDING

Response Codes

Code	Meaning
200	Purchase request processed.
400	Invalid request or missing idempotency key.
401	Missing or invalid API key, timestamp, or signature.
403	Access is forbidden.
409	Idempotency conflict or insufficient partner wallet balance.
422	Business-rule rejection, such as partner limit checks.
502	Upstream provider failure while processing the request.
503	Service temporarily unavailable (for example provider circuit open).
504	Upstream provider timeout.
500	Unexpected processing error.

When Telebirr confirms delivery but local platform finalization still needs reconciliation, the endpoint still returns 200 with transactionStatus: "FINALIZATION_PENDING" and the confirmed telebirrRef. Partners should treat this as delivered, not failed.

Integration Notes

• Always retry with the same Idempotency-Key after network timeouts.
• Treat non-2xx responses as non-delivered unless your integration has independent provider confirmation.
• Persist correlationId and telebirrRef for support and reconciliation workflows.