Webhooks

Partner callbacks from GatewayCallbackService when transactions complete.

Overview

Provide callbackUrl on process-transfer requests. RukaPay POSTs JSON to your URL when a transaction reaches SUCCESS or FAILED. Collections require callbackUrl.

Headers: Content-Type: application/json, User-Agent: RukaPay-Gateway/1.0. Timeout: 10 seconds.

When callbacks are sent

Immediately after process-transfer completes (SUCCESS or FAILED)
When MTN/Airtel inbound webhooks finalize a collection (webhook-processing.service)

Callback payload

Partner callback

{
  "partnerReference": "PARTNER-REF-123456",
  "status": "SUCCESS",
  "transactionId": "cm5abc123xyz",
  "mnoId": "MTN-FIN-987654",
  "mnoTransactionId": "MTN-FIN-987654",
  "amount": 50000,
  "fee": 1000,
  "totalCharged": 51000,
  "metadata": { "customerId": "12345", "orderId": "ORD-789" },
  "timestamp": "2026-05-21T10:30:45.000Z"
}

Fields

partnerReference — your reference from the request
status — SUCCESS or FAILED
transactionId — RukaPay transaction ID
mnoTransactionId — MTN/Airtel financial ID when applicable
amount, fee, totalCharged
metadata — echoed from your request
errorMessage — present on FAILED