Callbacks
Receive real-time transaction status updates via webhooks
Callbacks
When a transaction is completed, Bridge sends a POST request to the callback_url you provided in the original payment request. This eliminates the need to poll our API for status updates.
Callback URL Requirements
Your callback endpoint must:
- Be publicly accessible
- Accept POST requests with a JSON body
- Respond with HTTP
200
Sample Callback Payload
{
"collection_trans_id": null,
"trans_ref": "2220260609162313-03947541",
"payment_option": null,
"trans_id": "0982989097",
"trans_status": "000",
"customer_number": "233244000001",
"nw": "MTN",
"payment_mode": "MOM",
"amount": "0.21",
"message": "SUCCESSFUL"
}Callback Fields
| Field | Description |
|---|---|
collection_trans_id | Bridge's internal transaction ID |
trans_ref | Your original transaction ID (the transaction_id you submitted) |
payment_option | Payment option — not in use, can be ignored |
trans_id | The network's transaction ID |
trans_status | Transaction status code |
customer_number | Customer's phone number |
nw | Network of the customer's phone number (e.g. MTN, VOD, AIR) |
payment_mode | Payment mode used (e.g. MOM for Mobile Money) |
amount | Transaction amount |
message | Human-readable status description |
Handling the Callback
Use trans_status to determine the outcome of the transaction and update your system accordingly.
trans_status | Meaning | Recommended Action |
|---|---|---|
000 | Successful | Mark the transaction as successful and fulfil the order |
001 | Failed | Mark the transaction as failed and notify the customer |
002 | Pending | Transaction is still processing — wait for a follow-up callback |
003 | Cancelled | Mark the transaction as cancelled |
Use trans_ref to match the callback to the original transaction in your system.
For a full list of status codes, see Response Codes.
Missed Callbacks
If your system does not receive a callback (e.g. due to downtime or a network issue), you can query the transaction status directly using the Get Transaction Status endpoint. Pass the original transaction_id you submitted, and the response will include a status field that you should handle the same way as trans_status in the callback.