Integration Guides

Callbacks and Polling

Subscriber lookups and commits are asynchronous. The API call only confirms receipt. Afrisend sends the outcome later as a POST with a JSON body to your callback_url. Each operation's reference documents its callback payload.

Subscriber Lookup Callback

json

{
  "request_id": "LKP-20261012-0001",
  "tracking_id": "AG_20261012_2030166ee8992ece3dc4",
  "status": "success",
  "status_message": "The service request is processed successfully.",
  "recipient_data": { "CreditPartyName": "254712345678 - Wanjiru Kamau" }
}

Commit Callback

json

{
  "transaction_id": "in4E8EB52680",
  "tracking_id": "AG_20261012_20106e210e4e0c5f1202",
  "status": "success",
  "status_message": "The service request is processed successfully."
}

Handling Callbacks

Reply with HTTP 200 quickly, then process the callback in the background.
Match callbacks to your records by request_id (lookups) or transaction_id (commits).
Expect duplicate callbacks. Make your handler idempotent.

Polling Fallback

Note: Don't rely on callbacks alone. If a commit callback doesn't arrive within a few minutes, call checkTransactionStatus until the transaction reaches a final status (COLLECTED, FAILED, REVERSED, CANCELLED).

If a log request times out before you get the transaction_id, call getTransactionByRequestId with your request_id.

Transaction Flow Idempotency and Duplicates