创建代付订单

TIP

POST baseUrl + /api/payOut

HTTP请求头

请求头	必选	值
Content-Type	Y	application/json
MerchantId	Y	MerchantId
Sign	Y	Sign

HTTP请求体

参数名	必选	类型	示例值	字段说明
accountName	Y	string(32)	Jeck-Ma (名字在前-姓在后 中间使用 - 字符隔开 例子 嘉诚-李 )	收款人名称
accountNo	Y	string(32)	TRxxxxxxx	收款人账户
accountType	Y	int	1 请参考代付账户类型	账户类型
currency	Y	string(32)	TRY	货币代码
amount	Y	decimal(20,2)	[10-40000] (最多2位小数)	金额
mchOrderNo	Y	string(32)	1386556787811426305	商户订单号
notifyUrl	Y	String(250)	https://merchant.com/webhooks	回调地址
nonceStr	Y	string(32)	1863484722378907648	随机字符串
remark	Y	string(32)	remark	备注
idType	N	string(32)	暂不区分类型	代付收款人证件类型
idCard	N	string(32)	用户真实证件号 (如果填写了证件号就一定会 校验帐户和证件是否对应)	收款人证件号
phone	N	string(32)	+52xxxxxxx	收款人手机号
email	N	string(64)	example@maildomain.com	收款人邮箱

TIP

注意回调地址仅支持https或者http协议的地址，如果地址是ip地址，请务必使用公网IP。

HTTP响应体

参数名	类型	参数说明
merchantId	int	商户Id
mchOrderNo	string(32)	商户订单号
orderNo	string(32)	平台订单号
amount	decimal(20,2)	金额
fee	decimal(20,2)	手续费
orderStatus	string	订单状态 请参考代付订单状态枚举

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "100001",
    "mchOrderNo": "M1656907083234",
    "orderNo": "PAYOUT8232147367892025344",
    "amount": 100,
    "fee": 0,
    "orderStatus": "PROCESSING"
  }
}

查询代付订单

API EndPoint

POST baseUrl + /api/payOutQuery

请求参数

参数名	必选	类型	示例值	字段说明
mchOrderNo	N	string(32)	1863484722378907648	商户订单号
orderNo	N	string(32)	PAYOUT8551739282639106048	平台订单号
nonceStr	Y	string(32)	9459931608	随机字符串

TIP

我们建议优先使用orderNo（平台订单号），平台订单号和商户订单号至少需要传递一个。

请求示例

curl -L 'baseUrl/api/payOutQuery' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"mchOrderNo":"1863484722378907648","nonceStr":"9459931608","orderNo":"PAYOUT8551739282639106048"}'

响应参数

参数名	类型	说明
merchantId	int	商户Id
mchOrderNo	string(32)	商户订单号
orderNo	string(32)	平台订单号
channelOrderNo	string(32)	渠道订单号
amount	decimal(20,2)	金额
fee	decimal(20,2)	手续费
orderStatus	string(32)	代付订单状态枚举
resultDesc	string(64)	订单状态具体描述
completionTime	yyyy-MM-dd HH:mm:ss	订单完成完成时间

响应示例

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1863484722378907648",
    "orderNo": "PAYOUT8551739282639106048",
    "amount": "60000",
    "fee": "5150",
    "orderStatus": "PAYING",
    "completionTime": null,
    "resultDesc": null
  }
}

异步回调通知

通知地址由商户提供

POST Merchant NotifyUrl

异步通知请求参数

参数名	类型	说明
merchantId	int	商户Id
mchOrderNo	string(32)	商户订单号
orderNo	string(32)	平台订单号
channelOrderNo	string(32)	渠道订单号
amount	decimal(20,2)	金额
fee	decimal(20,4)	手续费
orderStatus	string(32)	代付订单状态枚举
resultDesc	string(64)	订单状态具体描述
completionTime	yyyy-MM-dd HH:mm:ss	订单完成完成时间

异步通知请求示例

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

订单结果反转处理

请注意，极少数的情况下代付订单会发生结果反转通知，您的回调处理逻辑应当考虑成功->失败，失败->成功状态的处理。

异步通知响应示例

{
  "status": "SUCCESS"
}

TIP

当回调响应HTTP状态码为200、301或302时，我们认为商户已经成功接收并处理回调, 其它状态我们会认为商户处理回调失败。

回调失败后会在1,2,4,8,16,32,64,128,256,512分钟重试，一共重试回调10次