Callback

This section explains how callbacks work and how to handle them.

Getting Started

To receive transaction callbacks:

• Configure your callback URL in the dashboard
• Use your encryption key to verify and decrypt data

What is a Payment Callback?

A payment callback is a mechanism where the payment gateway sends real-time updates to your server.

These updates include transaction statuses such as:

• success
• failed
• pending
• expired
• chargeback
• refunded

This removes the need to continuously poll APIs for status updates.

How It Works

1. Transaction Initiation

A customer initiates a payment on your platform.

2. Payment Processing

The gateway processes the transaction.

3. Callback Notification

The gateway sends a POST request to your callback URL.

4. Server Handling

Your server should:

• receive the callback
• decrypt the data (if applicable)
• verify the integrity of the payload
• update the transaction status

Callback Format

{
  "transaction_id": "123xyz",
  "status": "success",
  "amount": 10,
  "date": "2023-10-27T08:43:27.709Z",
  "utr": "123xxx88",
  "merchant_ref_no": "4777382",
  "encryptedData": "xyzllsndkwl=="
}

Field Description

• transaction_id → Unique transaction ID
• status → success, failed, expired, chargeback, refunded
• amount → Transaction amount
• date → ISO timestamp
• utr → Bank transaction reference
• merchant_ref_no → Merchant reference ID
• encryptedData → Encrypted transaction payload

Decryption

To verify transactions, decrypt encryptedData using your encryption key.

Example (Node.js)

function decryptParameters(input, secretKey) {
  const decryptedBytes = CryptoJS.AES.decrypt(input, secretKey);
  const decryptedData = decryptedBytes.toString(CryptoJS.enc.Utf8);
  return decryptedData;
}

You can implement this in any programming language.

Notes

• Your endpoint must accept POST requests
• Always decrypt encryptedData before processing
• Always validate data integrity
• Never expose your encryption key

Summary

• Callback = real-time transaction updates
• Sent via POST request
• Includes encrypted payload
• You decrypt → validate → process