API PAYOUT
About 5 min
Request
The Payout API enables merchants to initiate fund disbursement transactions to recipients.
Supported disbursement methods include:
Bank transfers
Digital wallets
Virtual accounts
Other electronic payment channels
Request Path:
sandbox:
https://sandbox-gateway.smilepayz.com/v2.0/disbursement/pay-out
production:https://gateway.smilepayz.com/v2.0/disbursement/pay-out
Header Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP content type specification Fixed value: application/json Required for proper request parsing |
| X-TIMESTAMP | M | String | ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+07:00 Note: Must be current server time within ±5 minutes |
| X-SIGNATURE | M | String | Digital signature for request authentication See Signature Generation |
| X-PARTNER-ID | M | String | Unique merchant identifier assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing Please enter merchantID |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| orderNo | M | String(32) | Unique transaction identifier for merchant tracking Format: Alphanumeric characters only Length: 6-32 characters Must be unique within merchant scope |
| purpose | M | String(64) | Human-readable transaction description Format: UTF-8 encoded string Length: 1-64 characters Used for transaction history and reporting |
| merchant | M | Object | Merchant identification and business information container Contains primary and sub-merchant details Required for transaction routing and settlement |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for transaction routing and settlement processing |
| merchantName | O | String | Registered business name of the merchant Format: UTF-8 encoded string Displayed in transaction records |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Required for sub-merchant transaction processing |
| subMerchantName | O | String | Sub-merchant business name for display purposes Format: UTF-8 encoded string Shown in transaction records |
| money | M | Object | Transaction amount and currency specification container Defines disbursement value and monetary unit Required for payment processing and settlement |
| currency | M | String | ISO 4217 currency code specification Fixed value: THB (Thai Baht) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents THB 200.00 Range: 100-999999999 |
| paymentMethod | M | String | Disbursement method specification Format: Predefined payment method codes Examples: KBANK, BBL, SCB Determines the disbursement channel used See Payment Method List |
| cashAccount | M | String(32) | Recipient account identifier for fund disbursement Format: Bank account number or e-wallet account Examples: Bank account (17385238451), Digital wallet account Must be valid and active account for successful transfer |
| callbackUrl | O | String(256) | Webhook notification endpoint URL Format: Valid HTTP/HTTPS URL Maximum length: 256 characters Receives real-time transaction status updates |
Example Body – Disbursement Request:
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001
{
"orderNo": "2000102900000000000001",
"paymentMethod": "KBANK",
"purpose": "Purpose For Disbursement from Java SDK",
"cashAccount": "17385238451",
"merchant": {
"merchantId": "20001"
},
"money": {
"amount": 200,
"currency": "THB"
}
}
Response
HTTP Response
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP response content type specification Fixed value: application/json Indicates JSON response format |
| X-TIMESTAMP | M | String | ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+07:00 |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| code | M | String | API response status code indicating operation result Format: Two-digit string Success: "00", Error: Other codes Used for programmatic response handling |
| message | M | String | Human-readable response status description Format: UTF-8 encoded string Provides detailed information about the operation result Localized based on request language |
| orderNo | M | String | Original merchant transaction identifier for reference Format: Same as request orderNo Used for transaction tracking and reconciliation |
| tradeNo | O | String | Internal transaction reference number for system tracking Format: System-generated alphanumeric string Used for internal transaction management and support |
| merchant | M | Object | Merchant information container with account details Contains merchant identification and account information See Merchant Model |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for transaction routing and settlement processing |
| merchantName | O | String | Registered business name of the merchant Format: UTF-8 encoded string Displayed in transaction records |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Required for sub-merchant transaction processing |
| subMerchantName | O | String | Sub-merchant business name for display purposes Format: UTF-8 encoded string Shown in transaction records |
| accountNo | O | String | Merchant account number for transaction processing Format: Alphanumeric string Used for transaction routing and settlement |
| money | M | Object | Transaction amount details with currency specification Contains confirmed disbursement amount and currency See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: THB (Thai Baht) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents THB 200.00 Range: 100-999999999 |
| disbursementTime | M | String | ISO 8601 datetime format (yyyy-MM-ddTHH:mm:ss±HH:mm) Example: 2020-12-17T10:55:00+07:00 Timestamp when disbursement was processed by the system |
| channel | M | Object | Disbursement processing channel details Contains payment method and recipient account information See Channel Model |
| paymentMethod | M | String | Disbursement method used for transaction processing Format: Predefined payment method codes Examples: KBANK, BBL, SCB Indicates the actual disbursement channel used |
| cashAccount | M | String | Recipient account identifier for fund disbursement Format: Bank account number or e-wallet account Used for disbursement processing and verification |
| accountName | O | String | Recipient account holder name for verification Format: UTF-8 encoded string Used for account verification and transaction records |
| status | O | String | Current transaction processing status Format: Predefined status codes Examples: PROCESSING, SUCCESS, FAILED See Status Model |
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
{
"code": "00",
"message": "successful",
"orderNo": "2000102900000000000001",
"tradeNo": "20001032432400001",
"status": "PROCESSING",
"disbursementTime": "2020-12-17T10:55:00+07:00",
"merchant": {
"merchantId": "10002",
"merchantName": "Betty",
"accountNo": "2000124234782342"
},
"money": {
"currency": "THB",
"amount": 10000
},
"channel": {
"paymentMethod": "KBANK",
"cashAccount": "17385238451",
"accountName": "test"
}
}
Notification/Callback
HTTP Request
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP notification content type specification Fixed value: application/json Indicates JSON payload format |
| X-TIMESTAMP | M | String | ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+07:00 |
| X-SIGNATURE | M | String | Digital signature for notification verification Format: Base64 encoded signature Used to verify notification authenticity See how to check this value |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| orderNo | M | String | Original merchant transaction identifier for reference Format: Same as request orderNo Used for transaction reconciliation and tracking |
| tradeNo | M | String | Internal transaction reference number for system tracking Format: System-generated alphanumeric string Used for internal transaction management and support |
| merchantId | M | String | Primary merchant identifier for transaction routing Format: Alphanumeric string Used for merchant identification and settlement processing |
| merchantName | M | String | Registered merchant business name for display Format: UTF-8 encoded string Shown in transaction records and reports |
| subMerchantId | O | String | Sub-merchant identifier for multi-level structures Format: Alphanumeric string Included when sub-merchant is involved in transaction |
| subMerchantName | O | String | Sub-merchant business name for display purposes Format: UTF-8 encoded string Included when sub-merchant is involved in transaction |
| paymentMethod | M | String | Payment method used for transaction processing Format: Predefined payment method codes Examples: KBANK, BBL, SCB Indicates the actual disbursement channel used |
| transactionTime | M | String | ISO 8601 datetime format (yyyy-MM-ddTHH:mm:ss) Timestamp when transaction was completed by payment provider |
| money | M | Object | Final transaction amount details with currency Contains confirmed disbursement amount and currency May differ from request amount due to fees or adjustments See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: THB (Thai Baht) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents THB 200.00 Range: 100-999999999 |
| status | M | String | Final transaction processing status Format: Predefined status codes Examples: SUCCESS, FAILED Indicates the final outcome of the transaction See Status Model |
Return
Important
Notification please return only string SUCCESS
{
"merchantId": "20001",
"merchantName": "test",
"money": {
"amount": 1000,
"currency": "THB"
},
"orderNo": "0TIn7z0G96HAGV8I734290310",
"status": "SUCCESS",
"tradeNo": "112200012412160218303176",
"transactionTime": "2024-12-16T02:18:30"
}
SUCCESS