Callback Responses

When a payout transfer is processed, our system will send a callback to your configured webhook URL. This document details the structure of these callback responses.

Success Response

When a transfer is successful, you will receive a callback with the following structure:

{
    "event": "payout.transfer.success",
    "code": "0x0200",
    "message": "Transaction Successful",
    "data": {
        "orderRefId": "order_ref_id",
        "clientRefId": "client_ref_id",
        "contactId": "contact_id",
        "firstName": "first_name",
        "lastName": "last_name",
        "email": "email",
        "phone": "phone",
        "amount": "amount",
        "status": "status",
        "utr": "bank_reference"
    }
}

Response Parameters

Parameter	Type	Description
event	string	Event type identifier (payout.transfer.success)
code	string	Success code (0x0200)
message	string	Success message
data.orderRefId	string	Order reference ID
data.clientRefId	string	Client reference ID
data.contactId	string	Contact ID of the recipient
data.firstName	string	First name of the recipient
data.lastName	string	Last name of the recipient
data.email	string	Email address of the recipient
data.phone	string	Phone number of the recipient
data.amount	string	Transfer amount
data.status	string	Status of the transaction
data.utr	string	Unique Transaction Reference from the bank

Failure Response

When a transfer fails, you will receive a callback with the following structure:

{
    "event": "payout.transfer.failed",
    "code": "0x0202",
    "message": "Transaction Failed",
    "data": {
        "orderRefId": "order_ref_id",
        "clientRefId": "client_ref_id",
        "contactId": "contact_id",
        "firstName": "first_name",
        "lastName": "last_name",
        "email": "email",
        "phone": "phone",
        "amount": "amount",
        "status": "status",
        "reason": "failed_message"
    }
}

Response Parameters

Parameter	Type	Description
event	string	Event type identifier (payout.transfer.failed)
code	string	Error code (0x0202)
message	string	Error message
data.orderRefId	string	Order reference ID
data.clientRefId	string	Client reference ID
data.contactId	string	Contact ID of the recipient
data.firstName	string	First name of the recipient
data.lastName	string	Last name of the recipient
data.email	string	Email address of the recipient
data.phone	string	Phone number of the recipient
data.amount	string	Transfer amount
data.status	string	Status of the transaction
data.reason	string	Reason for the failure

Handling Callbacks

Ensure your webhook endpoint is configured to:

1. Process the callback data securely
2. Respond with a 200 OK status code promptly
3. Implement idempotency checks to handle duplicate callbacks
4. Update your systems based on the received status

Note: You should validate the authenticity of callbacks by implementing signature verification.