Create Payout Order

HTTP Request

API EndPoint

POST baseUrl + /api/payOut

Request Parameters

Parameter	Required	Type	Description	Example
accountName	Y	string(32)	Payee name limited to 64 characters	John
accountNo	Y	string(32)	Payee bank account number
accountType	Y	int	Account type	Please refer to [payout account type]((appendix.md#payout-account-type)
currency	Y	string(32)	Currency code	INR
amount	Y	decimal(20)	Amount	[10,10000]
ifscCode	Y	string(32)	Payee account number ifsc, 4 letters + '0' + 6 digits or letters	Example: SBIN0014148
mchOrderNo	Y	string(32)	Merchant order number	1386556787811426305
notifyUrl	Y	String(250)	Callback address	https://merchant.com/webhooks
nonceStr	Y	string(32)	Random number	1863484722378907648
phone	Y	string(32)	Payee's mobile number, the real mobile number of the beneficiary	+52xxxxxxx
remark	Y	string(32)	Remark (Please use English characters or Spanish without accents)	remark
idType	N	string(32)	[ID Type of the beneficiary](appendix.md#ID Type of the beneficiary)	1
idCard	N	string(32)	Payee's ID number, which must be the account opening ID number corresponding to the beneficiary's account	User's real ID number
email	N	string(64)	The recipient's email address must be a valid email address and cannot be repeated for different users	example@maildomain.com

Request Example

curl -L 'baseUrl/api/payOut' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"nonceStr":"test001","accountName":"Test","accountNo":"10000000003","accountType":"BANK_CARD_ACCOUNT","currency":"INR","amount":2704.00,"mchOrderNo":"order000000001","notifyUrl":"https://test.com/cashy/payOut/callback","idType":"ID_CARD","idCard":"872966212003","phone":"1340000003","remark":"PayOut","ifscCode":"ZSBL0000311"}'

Response Parameters

Parameter	Type	Description
merchantId	int	Merchant Id
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 Statuspls refer toPayout Order Status Enum

Response Example

SUCCESS

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "order000000001",
    "orderNo": "PAYOUT8232147000000000001",
    "amount": 100,
    "fee": 0,
    "orderStatus": "PROCESSING"
  }
}

FAIL

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

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