Create Payout Order
HTTP Request
TIP
POST baseUrl + /api/payOut
Request Headers
| HeaderName | Required | Value |
|---|---|---|
Content-Type | Y | application/json |
MerchantId | Y | MerchantId |
Sign | Y | Sign |
RequestBody
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
accountName | Y | string(40) | John | Beneficiary Name |
accountNo | Y | string(32) | pls refer to Payout Account Type | Beneficiary Account |
accountType | Y | int | pls refer toPayout Account Type | Beneficiary Account Type |
currency | Y | string(32) | MXN | Currency code |
amount | Y | decimal(20,0) | [40,15000] | Amount(only support integer) |
bankId | Y | int | pls refer toPayout Bank List | Bank id |
mchOrderNo | Y | string(32) | P123456 | Merchant order number |
notifyUrl | Y | string(250) | http://abc.com/ | webhooks (callback) address |
nonceStr | Y | string(32) | 16283812xxxx | Random string |
idType | N | string(32) | No distinction between types for the time being | Payout Payee ID Type |
idCard | N | string(32) | User's real ID number | Beneficiary ID number |
phone | N | string(32) | +52xxxxxxx | Beneficiary phonenumber |
email | N | string(32) | xyz@gamil.com | Beneficiary email |
remark | Y | string(32) | remark | Order remarks |
TIP
Note that callback/webhook addresses only support https or http protocol addresses. If the address is an ip address, be sure to use a public domain name.
ResponseBody
| Parameter | Type | Parameter Description |
|---|---|---|
merchantId | int | MerchantId |
mchOrderNo | string(32) | Merchant order number |
orderNo | string(32) | Platform order number |
amount | decimal(20,0) | Amount |
fee | decimal(20,0) | fee |
orderStatus | string | Order Statuspls refer toPayout Order Status Enum |
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "100001",
"mchOrderNo": "M1656907083234",
"orderNo": "PAYOUT8232147367892025344",
"amount": 100,
"fee": 0,
"orderStatus": "PROCESSING"
}
}Payout payment sequence diagram
- The merchant requests the /api/payOut interface to submit a payment order.
- Cashy pre-processes payment orders. (Verify some necessary parameters)
- Return the processing result to the merchant. (If successfully received, the platform order number and other information will be returned; if failed, the corresponding synchronization rejection reason will be returned)
X. After the merchant obtains the result of 3, he can check the order status at any time through the PayoutQuery API.
- SPEI will verify the order. If the verification passes, it will be sent to the beneficiary bank. If it fails, the reason for the failure will be returned.
W1. For the first order callback, if the transaction is rejected by the SPEI system, it will be notified that the order failed and the reason for the order failure will be carried. If it is successfully sent to the beneficiary bank, the callback order will be successful.
- The beneficiary bank verifies the transaction. If the verification passes, it will be deposited into beneficiary account. If it fails, the failure reason will be returned (eg : account block,account not exits). （This process takes about 2 minutes）
- After receiving the payment, the user takes the initiative to refund the money.
W2. If the beneficiary bank rejects the payment/the user actively initiates a refund, there will be a second order callback and the failure reason will be returned.
Query Payout Order
HTTP Request
TIP
POST baseUrl + /api/payOutQuery
Request Headers
| HeaderName | Required | Value |
|---|---|---|
Content-Type | Y | application/json |
MerchantId | Y | MerchantId |
Sign | Y | Sign |
RequestBody
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
mchOrderNo | N | string(32) | P123456 | Merchant order number |
orderNo | N | string(32) | PAYIN12345 | Platform order number |
nonceStr | Y | string(32) | 1628381288000 | Random string |
TIP
We recommend using orderNo (platform order number) first. At least one of the platform order number and merchant order number needs to be passed.
ResponseBody
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "100001",
"mchOrderNo": "M1656756338536",
"orderNo": "PAYOUT8231515112790892544",
"amount": 100.0,
"fee": null,
"orderStatus": "PAYING",
"completionTime": null,
"resultDesc": "SUCCESS"
}
}| Parameter | Type | Description |
|---|---|---|
merchantId | int | MerchantId |
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) | Order Statuspls refer toPayout Order Status Enum |
completionTime | date | Completion time yyyy-MM-dd HH:mm:ss |
resultDesc | string(64) | Order Status,pls refer toOrder Status Description |
Async Webhook Notification
HTTP Request
TIP
POST : notifyUrlnotifyUrlis provided by the merchant
Request Headers
| HeaderName | Required | Value |
|---|---|---|
Content-Type | Y | application/json |
MerchantId | Y | MerchantId |
Sign | Y | Sign |
Webhook RequestBody
{
"orderStatus": "SUCCESS",
"amount": 100.0,
"fee": 0,
"mchOrderNo": "2a6421c4-3758-4d1a-b47e-f7d0e7133f9e",
"merchantId": "100001",
"orderNo": "PAYOUT8388679728902370944",
"completionTime": "2022-08-08 08:08:08",
"resultDesc": "SUCCESS"
}| Parameter | Type | Description |
|---|---|---|
merchantId | int | MerchantId |
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) | pls refer toPayout Order Status |
resultDesc | string(64) | pls refer toOrder Status Description |
completionTime | date | Complete time |
TIP
fee and completionTime only have a value if the order is successfully paid.
TIP
Please respond with SUCCESS if the process is successful. For other responses, we will consider the callback to have failed. After the callback fails, it will be retried in 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 minutes, and the callback will be retried 10 times in total.