Callback Operations - Callback Parameters (Payout)
Comprehensive guide to payout callback payload structure, fields, and signature verification
Overview
When a payout manual callback is triggered, ZenPay sends a structured payload to the merchant's callback URL. This page details the complete payload structure, field descriptions, and signature verification process.
Understanding these parameters is crucial for merchants to properly handle payout notifications and update their systems accordingly.
Security Notice: All callback payloads include HMAC-SHA256 signatures for verification. Always validate signatures before processing callbacks.
HTTP Request Structure
ZenPay sends payout callbacks as HTTP POST requests to the merchant's configured callback URL with specific headers and payload structure.
HTTP Headers
| Header | Type | Description | Example |
|---|---|---|---|
|
Content-Type
|
string | Request content type | application/json |
|
X-Signature
|
string | HMAC-SHA256 signature for verification | a1b2c3d4e5f6... |
|
User-Agent
|
string | ZenPay identification string | ZenPay-Payout/1.0 |
Complete HTTP Request Example
POST {merchant_callback_url}
Content-Type: application/json
X-Signature: a1b2c3d4e5f67890abcdef1234567890fedcba0987654321
User-Agent: ZenPay-Payout/1.0
{
"biller_code": "202500039",
"ref_doc": "INV-2024-9990222",
"amount": "150.50",
"status": "APPROVED",
"bank_code": "ARBKMYKL",
"bank_account": "1234567890123",
"bank_acc_holder": "John Doe",
"member_id": "CUSTOMER001",
"processed_at": "2025-01-15T10:30:00Z",
"settlement_date": "2025-01-15"
}
Payload Parameters
The JSON payload contains essential payout information that merchants need to process and update their systems.
Parameter Reference
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
|
biller_code
|
string | Yes | Merchant identifier code | "202500039" |
|
ref_doc
|
string | Yes | Unique payout reference document | "INV-2024-9990222" |
|
amount
|
string | Yes | Payout amount with 2 decimal places | "150.50" |
|
status
|
string | Yes | Current payout status | "APPROVED" |
|
bank_code
|
string | Yes | Bank swift code (uppercase) | "ARBKMYKL" |
|
bank_account
|
string | Yes | Recipient bank account number | "1234567890123" |
|
bank_acc_holder
|
string | Yes | Bank account holder name | "John Doe" |
|
member_id
|
string | Yes | Customer/member identifier from original payout request | "CUSTOMER001" |
|
processed_at
|
string | Yes | Callback processing timestamp (ISO 8601 format) | "2025-01-15T10:30:00Z" |
|
settlement_date
|
string | Optional | Date when payout was settled (YYYY-MM-DD format) | "2025-01-15" |
Status Values
The status field indicates the current state of the payout transaction.
Available Status Values
| Status | Description | Action Required |
|---|---|---|
| FRESH | Payout request has been created and is pending review | Await admin review and approval |
| PENDING | Payout is in progress, awaiting processing | No action required, await final status update |
| APPROVED | Payout has been approved and will be processed | Await processing completion |
| DECLINED | Payout request has been declined by admin | Handle declined payout, review and potentially resubmit |
| CANCELLED | Payout request has been cancelled | Update system to reflect cancellation |
| ERROR | Payout processing encountered an error | Review error details and potentially retry |
Signature Verification
The X-Signature header contains an HMAC-SHA256 signature that merchants must verify to ensure callback authenticity and prevent tampering.
Complete Signature Guide: For detailed steps on signature generation and verification, including implementation examples and best practices, see the Signature Generation page.
Data Types & Formats
Understanding the specific data types and formats used in payout callbacks helps ensure proper processing and validation.
Format Reference
| Data Type | Format | Example | Validation Rules |
|---|---|---|---|
| Amount | String with 2 decimal places | "150.50" | Always includes .XX format |
| Bank Code | 8-character uppercase string | "ARBKMYKL" | Swift code format |
| Timestamp | ISO 8601 with UTC timezone | "2025-01-15T10:30:00Z" | Always ends with 'Z' |
| Date | YYYY-MM-DD format | "2025-01-15" | ISO 8601 date only |