​
Callbacks

Callbacks are a crucial part of TheBridge API’s asynchronous communication system. They allow our system to notify your application about the status of transactions in real-time, ensuring you’re always up-to-date with the latest information.

​
Overview

When you initiate a transaction using our API, we process it asynchronously. This means that instead of waiting for the transaction to complete before responding, we immediately return a response acknowledging that we’ve received your request. The actual processing happens in the background. To keep you informed about the transaction’s progress, we send callbacks to a URL you specify. These callbacks are HTTP POST requests containing JSON data about the transaction status.

​
Callback URL

When making a payment request, you should include a callback_url parameter. This is the endpoint where we’ll send status updates about the transaction. For example: 
{
  "callback_url": "https://yourapp.com/callback"
}
Ensure that this endpoint is set up to receive POST requests and can handle the callback data we send.

​
Callback Data Structure

Here’s an example of the callback data you’ll receive: 
  {
    "trans_ref": "POY33082172",
    "trans_id": "0000005087491181",
    "trans_status": "000/SUCCESS",
    "message": "SUCCESSFUL",
    "customer_number": "233XXXXXXXXX",
    "nw": "MTN",
    "payment_mode": "MOM",
    "payment_option": "MOM"
  }
Let’s break down each field:

​
trans_ref

This is the transaction_id you provided when initiating the transaction on make_payment endpoint. It helps you match the callback to the original transaction in your system.

​
trans_id

This is a unique identifier for the transaction in our system. You can use this ID when querying our API for more details about the transaction.

​
trans_status

This field provides a detailed status code. It consists of a numeric code followed by a short description. The first three characters of this field indicate the transaction status:
  • “000”: The transaction was successful.
  • “001”: The transaction is still being processed.
  • “002”: The transaction failed.
For example, a status of “000/SUCCESS” would indicate a successful transaction. To interpret the status:
  1. Extract the first three characters of the trans_status field.
  2. Use this numeric code to determine the transaction status.
  3. The text after the slash provides additional human-readable information.
Here’s how you might handle this in your code: 
const statusCode = trans_status.substring(0, 3);

switch (statusCode) {
  case '000':
    console.log('Transaction successful');
    break;
  case '001':
    console.log('Transaction pending');
    break;
  default:
    console.log('Transaction failed');
}
Refer to our Response Codes documentation for a complete list of status codes and their meanings.

​
message

This field provides a human-readable description of the transaction status. Common values include:
  • “SUCCESSFUL”: The transaction was completed successfully.
  • “FAILED”: The transaction failed to process.
  • “PENDING”: The transaction is still being processed.

​
customer_number

The phone number of the customer who made the payment. This is in the international format without the ’+’ sign (e.g., “233XXXXXXXXX” for a Ghanaian number).

​
nw

The network provider used for the transaction. For example:
  • “MTN” for MTN Mobile Money
  • “TEL” for Telecel Cash
  • “AIR” for AirtelTigo Money

​
payment_mode

The mode of payment used. For example:
  • “MOM” for Mobile Money
  • “CRD” for Card payments

​
payment_option

This field typically mirrors the payment_mode, providing additional clarity on the payment method used.

​
Handling Callbacks

When you receive a callback, you should:
  1. Verify the callback’s authenticity (see Security Considerations below).
  2. Update your local records with the new transaction status.
  3. Trigger any necessary actions in your system (e.g., fulfilling an order if the payment was successful).
  4. Respond to the callback with a 200 OK status to acknowledge receipt.
Here’s a simple example of how you might handle a callback in a Node.js Express application: 
  app.post('/api/payment-callbacks', (req, res) => {
    const { trans_ref, trans_id, trans_status, message } = req.body;
    // Verify the callback (implementation depends on your security measures)
    if (!verifyCallback(req)) {
      return res.status(403).send('Invalid callback');
    }
  
    // Update local records
    updateTransaction(trans_ref, trans_status);
    
    // Trigger any necessary actions
    if (trans_status === '000/SUCCESS') {
      fulfillOrder(trans_ref);
    }

    // Acknowledge receipt of the callback
    res.status(200).send('OK');
  });

​
Security Considerations

To ensure the security of your system, always verify the authenticity of callbacks before processing them. Here are some measures you can implement:
  1. IP Whitelisting: Only accept callbacks from TheBridge API’s known IP addresses.
  2. HTTPS: Ensure your callback URL uses HTTPS to encrypt the data in transit.
  3. Signature Verification: We include a digital signature with each callback. Verify this signature to ensure the callback hasn’t been tampered with.
For more details on implementing these security measures, please refer to our Security Best Practices guide.