Data Package Activation

Use this endpoint to purchase and activate a data package for a recipient mobile number.

Flow

Endpoint

POST /data-packages/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.
offerId	string	Yes	Max 128 chars. Example: DP-ETHIO-1GB-7D.
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/data-packages/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: 2e9c7260-e8cc-4ce5-8b7c-75a33273d6ff" \
  -d '{
    "msisdn": "+251911234567",
    "offerId": "DP-ETHIO-1GB-7D",
    "originatingCountry": "US",
    "foreignCurrencyAmount": 1.77,
    "exchangeRate": 56.5
  }'

{
  "msisdn": "+251911234567",
  "offerId": "DP-ETHIO-1GB-7D",
  "originatingCountry": "US",
  "foreignCurrencyAmount": 1.77,
  "exchangeRate": 56.5
}

Example Response

{
  "id": 98422,
  "correlationId": "data_01HWJ7VHHZ37VZB6E7N2C9F4Q1",
  "recipientPhone": "+251911234567",
  "amountEtb": 100,
  "transactionStatus": "COMPLETED",
  "telebirrRef": "TB-240427-000124",
  "message": "Data package activation completed successfully."
}

transactionStatus can be:

• COMPLETED
• FINALIZATION_PENDING

Response Codes

Code	Meaning
200	Activation 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.

Integration Notes

• Reuse the same Idempotency-Key only when retrying the same request payload.
• Persist correlationId and telebirrRef for reconciliation and support.
• Handle FINALIZATION_PENDING as delivered with pending local reconciliation, not as failure.