Create Payout Order

API EndPoint

POST baseUrl + /api/payOut

Request Parameters

Parameter	Required	Type	Description	Example
accountName	Y	string(40)	Beneficiary Account Name
accountNo	Y	string(32)	Beneficiary Account Number
accountType	Y	int	Account Type	Payout Account Type
currency	Y	string(32)	Currency code	MXN
amount	Y	decimal(20,0)	Amount	[40,15000]
bankId	Y	int	Bank Id	38 Payout Bank Query
mchOrderNo	Y	string(32)	Merchant order number
notifyUrl	Y	String(250)	Webhooks url	https://merchant.com/webhooks/payout
nonceStr	Y	string(32)	Random string	1863484722378907648
remark	Y	string(32)	Remark	Please use English characters or unaccented Spanish
idType	N	string(32)	Beneficiary IdCard Type
idCard	N	string(32)	Beneficiary IdCard Number
phone	N	string(32)	Beneficiary phone number
email	N	string(64)	Beneficiary phone number

TIP

The bank support list is subject to the actual support status of the production environment. It is recommended that you call our bank list query interface to confirm the production bank support status before entering the production environment.

Request Example

curl -L 'baseUrl/api/payOut' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"accountName":"Bob Jeck","accountNo":"1234567891011","accountType":"3","amount":"60000","bankId":"1","currency":"MXN","email":"bobs@gmail.com","mchOrderNo":"697670130731094","nonceStr":"7445560671","notifyUrl":"https://merchant.com/mxn/payout","phone":"6285767828472","remark":"payout order"}'

Response Parameters

Parameter	Type	Description
merchantId	int	Merchant id
mchOrderNo	string(32)	Merchant order number
orderNo	string(32)	Platform order number
amount	decimal(20,0)	Amount
fee	decimal(20,0)	Fee
orderStatus	string	Payout Order Status Enum

Response Example

Success

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "697670130731094",
    "orderNo": "PAYOUT8551827184491839488",
    "amount": "60000",
    "fee": "0",
    "orderStatus": "PROCESSING"
  }
}

Some Error

{
  "msg": "System_error",
  "code": 500
}

Payout sequence diagram

1. The merchant requests the /api/payOut interface to submit a payment order.
2. Cashy pre-processes the payment order. (Check some necessary parameters)
3. Return the processing result to the merchant. (If the receipt is successful, the platform order number and other information will be returned. If it fails, the corresponding synchronous rejection reason will be returned)

X. When the merchant obtains the result of 3, he can query the order status at any time through the query payment order interface.

4. SPEI will verify the order. If the verification is passed, it will be sent to the receiving bank. If it fails, the failure reason will be returned.

W1. The first order callback, if the transaction is rejected by the SPEI system, the order failure will be notified, and the order failure reason will be carried. If it is successfully sent to the receiving bank, the order success will be called back.

5. The receiving bank verifies the transaction. If the verification is passed, it will be deposited into the receiving customer account. If it fails, the failure reason will be returned. (This process takes about two minutes)
6. After the user receives the money, he actively operates the refund.

W2. If the receiving bank refuses to accept the payment/the user initiates a refund, there will be a second order callback and the reason for the failure will be returned.

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"}'

Webhooks-Success

{
  "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"
}

Webhooks-Fail

{
  "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