Create Payout Order
HTTP Request
API EndPoint
POST baseUrl
+ /api/payOut
Request Parameters
Parameter | Required | Type | Description | Example |
---|---|---|---|---|
accountName | Y | string(32) | Beneficiary Name | Brandme |
accountNo | Y | string(32) | Beneficiary Account | 646180000000000007 |
accountType | Y | int | Beneficiary Account Type | pls refer toPayout Account Type |
currency | Y | string(32) | Currency code | COP |
amount | Y | decimal(20,2) | Amount 10000-5000000 | 10000 |
bankId | Y | int | Bank id ) | pls refer topayout-bank-list-query |
mchOrderNo | Y | string(32) | Merchant order number | 1386556787811426305 |
notifyUrl | Y | string(250) | webhooks (callback) address | https://merchant.com/webhooks |
nonceStr | Y | string(32) | Random string | 1863484722378907648 |
idType | Y | string(32) | Payout Payee ID Type | pls refer toPayout Payee ID Type |
idCard | Y | string(32) | Beneficiary ID number | |
phone | N | string(32) | Beneficiary phonenumber | +52xxxxxxx |
email | N | string(32) | Beneficiary email | xyz@gamil.com |
remark | Y | string(32) | Order remarks | remark |
TIP
Regarding the idType
field, please refer to the actual document type used when opening the recipient bank account. Inconsistency will result in payment failure.
Example: If a user opens an account using a NIT ID, and the ID type used to initiate payment is CC, payment will fail.
Request Example
curl -L 'baseUrl/api/payOut' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"amount":50000.00,"bankId":33,"idType":"1","accountName":"Jeson","mchOrderNo":"order00000001","idCard":"43912345","accountNo":"3023612345","accountType":"0","notifyUrl":"https://xxxxxx.com/notify","currency":"COP","remark":"remark","nonceStr":"123456789"}'
Response Parameters
Parameter | Type | Description |
---|---|---|
merchantId | int | MerchantId |
mchOrderNo | string(32) | Merchant order number |
orderNo | string(32) | Platform order number |
amount | decimal(20,2) | Amount |
fee | decimal(20,2) | fee |
orderStatus | string | Order Status,pls refer toPayout Order Status Enum |
Response Example
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "1002001",
"mchOrderNo": "697670130731094",
"orderNo": "PAYOUT8551827184491839488",
"amount": "60000",
"fee": "0",
"orderStatus": "PROCESSING"
}
}
{
"msg": "System_error",
"code": 500
}
Query Payout Order
API EndPoint
POST baseUrl
+ /api/payOutQuery
Request Parameters
Parameter | Required | Type | Example | Description |
---|---|---|---|---|
mchOrderNo | N | string(32) | 1863484722378907648 | Merchant order number |
orderNo | N | string(32) | PAYOUT8551739282639106048 | Platform order number |
nonceStr | Y | string(32) | 9459931608 | Random string |
TIP
We recommend using orderNo (platform order number) first. At least one of the platform order number and the merchant order number must be passed.
Request Example
curl -L 'baseUrl/api/payOutQuery' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"mchOrderNo":"1863484722378907648","nonceStr":"9459931608","orderNo":"PAYOUT8551739282639106048"}'
Response Parameters
Parameter | Type | Description |
---|---|---|
merchantId | int | Merchant id |
mchOrderNo | string(32) | Merchant order number |
orderNo | string(32) | Platform order number |
channelOrderNo | string(32) | Channel order number |
amount | decimal(20,2) | Amount |
fee | decimal(20,2) | Fee |
orderStatus | string(32) | Payout Order Status Enum |
resultDesc | string(64) | Order Status Description |
completionTime | yyyy-MM-dd HH:mm:ss | Completion time |
Response Example
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "1002001",
"mchOrderNo": "1863484722378907648",
"orderNo": "PAYOUT8551739282639106048",
"amount": "60000",
"fee": "5150",
"orderStatus": "PAYING",
"completionTime": null,
"resultDesc": null
}
}
Async Webhook Notification
The webhooks url is provided by the merchant
POST Merchant NotifyUrl
Webhook Request Parameters
Parameter | Type | Description |
---|---|---|
merchantId | int | Merchant id |
mchOrderNo | string(32) | Merchant order number |
orderNo | string(32) | Platform order number |
channelOrderNo | string(32) | Channel order number |
amount | decimal(20,2) | Amount |
fee | decimal(20,4) | Fee |
orderStatus | string(32) | Payout Order Status Enum |
resultDesc | string(64) | Order Status Description |
completionTime | yyyy-MM-dd HH:mm:ss | Completion time |
Webhook Request Example
curl -L 'merchant.com/webhools/payout' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"amount":60000.00,"completionTime":"2024-12-02 08:42:54","fee":5150.0000,"mchOrderNo":"1863484722378907648","merchantId":"3002124","nonceStr":"1733103774518","orderNo":"PAYOUT8551739282639106048","orderStatus":"SUCCESS","payType":"11"}'
{
"amount": 60000.0,
"completionTime": "2024-12-02 08:42:54",
"fee": 5150.0,
"mchOrderNo": "1863484722378907648",
"merchantId": "1002001",
"nonceStr": "1733103774518",
"orderNo": "PAYOUT8551739282639106048",
"orderStatus": "SUCCESS",
"payType": "11"
}
{
"amount": 60000.0,
"completionTime": "2024-12-02 08:42:54",
"fee": 5150.0,
"mchOrderNo": "1863484722378907648",
"merchantId": "1002001",
"nonceStr": "1733103774518",
"orderNo": "PAYOUT8551739282639106048",
"orderStatus": "FAIL",
"resultDesc": "ACCOUNT NOT EXITS",
"payType": "11"
}
Order result reversal processing
Please note that in rare cases, a payment order will have a result reversal notification. Your callback processing logic should consider the processing of success->failure and failure->success status.
Webhook Response Example
{
"status": "SUCCESS"
}
TIP
When the webhooks response HTTP status code is 200, 301 or 302, we believe that the merchant has successfully received and processed the callback. For other statuses, we believe that the merchant has failed to process the callback.
After the webhooks fails, it will be retried in 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 minutes
, and the webhooks will be retried 10 times in total