Payment Operations - Initiate Payout
Initiate payout transactions for your merchants
Overview
Use this endpoint to initiate a payout transaction to a recipient bank account. Provide payout details including amount, currency, and recipient banking information.
This endpoint requires Signature Authentication, IP Whitelisting, and is subject to Rate Limiting.
Request
Http Method & URL
POST /v1/payouts/initiate
Headers
| Header | Type | Required | Description |
|---|---|---|---|
|
Content-Type
|
string | Yes | application/json |
Validation Rules: Amount must be a decimal with exactly 2 decimals and greater than 0. Bank account must be numeric (dashes allowed). Reference document must be unique. Required fields must not be empty. Timestamp must be in ISO8601 UTC format.
Timestamp Validation: Requests with timestamps older than 5 minutes will be rejected. Ensure your system clock is synchronized with UTC.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
biller_code |
string | Yes | Merchant identifier |
amount |
string | Yes | Payout amount with 2 decimal places |
currency |
string | Yes | Currency code (e.g., "MYR") |
ref_doc |
string | Yes | Unique reference document |
bank_account |
string | Yes | Recipient bank account number |
bank_name |
string | Yes | Recipient bank name |
member_id |
string | Yes | Member identifier |
bank_acc_holder |
string | Yes | Bank account holder name |
bank_code |
string | Yes | Bank code |
return_url |
string | No | Return URL |
callback_url |
string | No | Callback URL |
timestamp |
string | Yes | Request timestamp in ISO8601 UTC format (e.g., "2024-01-15T10:30:00Z") |
Request Body Example
{
"biller_code": "MERCHANT001",
"amount": "100.50",
"currency": "MYR",
"ref_doc": "PAYOUT123456",
"bank_account": "1234567890",
"bank_name": "Maybank",
"member_id": "MEMBER001",
"bank_acc_holder": "John Doe",
"bank_code": "MAYBANK",
"return_url": "https://merchant.com/return",
"callback_url": "https://merchant.com/callback",
"timestamp": "2024-01-15T10:30:00Z"
}
Response
Success Response (201)
{
"success": true,
"message": "Payout initiated successfully",
"data": {
"pay_ref": "INV-2024-9990222",
"pay_amount": "150.50",
"pay_datetime": "20250717131328",
"pay_memberid": "CUSTOMER001"
}
}
Validation Error Response (400)
{
"success": false,
"message": "Payout validation failed",
"errors": [
{
"field": "general",
"message": "Duplicate reference document: INV-2024-02219990222"
}
]
}
Authentication Error Response (401)
{
"success": false,
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Invalid API key"
},
"timestamp": "2025-07-15T08:09:18Z"
}
Validation Error Response (422)
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"fields": [
{
"field": "timestamp",
"message": "Request timestamp is expired. Requests must be made within 5 minutes",
"code": "TIMESTAMP_EXPIRED",
"value": "2024-01-15T10:25:00Z"
},
{
"field": "amount",
"message": "Amount must be greater than 0",
"code": "INVALID_VALUE",
"value": "-10.50"
},
{
"field": "bank_account",
"message": "Bank account must be numeric",
"code": "INVALID_FORMAT",
"value": "abc123"
}
]
},
"timestamp": "2025-07-15T08:09:18Z"
}