notifyPayment
万里汇使用此接口进行支付结果通知。集成商收到通知后需要做出回应。
接口结构
万里汇接口报文结构包括:请求头,请求体。关于头信息,详见:
注:集成商发送响应前需要正确加签,详见:发送响应:加签
请求参数
字段名 | 数据类型 | 是否为必填字段 | 描述 |
result | Result 对象 | 是 | 支付结果 |
notifyType | 字符串 | 是 | 万里汇通知的类型 取值范围:
|
payToAmount | Amount 对象 | 是 | 本次支付中,应付金额(万里汇视角) |
payToId | 字符串 | 是 | 针对每笔支付,万里汇返回的唯一标识ID。 更多信息:
|
payToRequestId | 字符串 | 是 | 由商户生成的支付请求号。 更多信息:
|
paymentId | 字符串 | 是 | 万里汇受理支付后返回的唯一支付受理ID 更多信息:
|
paymentTime | DateTime 对象 | 是 | 支付受理成功的返回时间
|
paymentAmount | Amount 对象 | 是 | 本次支付中,向买家应收金额(万里汇视角) |
paymentDetailSummaries | 是 | 买家支付工具概要信息 |
请求处理
在收到万里汇的请求之后,集成商需要向万里汇发送响应信息,以确认信息已收到。
集成商需要注意:
- 集成商在发送响应信息之前必须加验签,加验签方法与请求API签名方式一致。关于如何加验签,参考:生成签名及加验签。
- 方法为HTTP
POST
- URI 与 createCashierPayment 接口中
paymentNotifyUrl
相同。举例:当通知地址为https://{domain_name}.com/in1d/conasdtroller/pay/manag
时,URI为:/in1d/conasdtroller/pay/manag
响应头结构:
相应头参数 | 是否为Required | 范例 |
Signature | Yes | Signature: algorithm=RSA256, keyVersion=2, signature=***** |
Content-Type | Yes | Content-Type: application/json; charset=UTF-8 |
Client-Id | Yes | Client-Id: ***** |
Response-Time | Yes | Response-Time: 2019-04-04T12:08:56+08:00 |
响应头范例:
{
"headers": {
"Content-Type": "application/json",
"client-id": "*****",
"response-time": "2022-03-07T07:49:27Z",
"signature": "algorithm=RSA256,keyVersion=1,signature=VelVji6jp8*****"
}
}
更多信息,参考:API概览章节
范例响应:
{
"result":{
"resultStatus":"S",
"resultCode":"SUCCESS",
"resultMessage":"success"
}
}
如果集成商不向万里汇发送响应信息,万里汇会重新发送请求通知。万里汇重发通知的规则为:
- 重试总数:7次
- 两次重发请求之间的间隔:2分钟,10分钟,10分钟,1小时,2小时,6小时,15小时
响应参数
字段名 | 数据类型 | 是否为必填字段 | 描述 |
result | 是 | 本次万里汇通知到商户,商户受理通知的结果 |
错误码
resultCode | resultStatus | resultMessage | 处理建议 |
SUCCESS | S | Success | |
PROCESS_FAIL | F | A general business failure occurred. Do not retry. | 需要人工介入。联系万里汇技术支持以解决此问题 |
PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. | 参考API文档页面以确认请求头和传参是否正确 |
UNKNOWN_EXCEPTION | U | The API call is failed, which is caused by unknown reasons. | 服务器忙。若稍后重试问题依旧,联系万里汇技术支持以解决问题 |
范例
请求
{
"notifyType": "PAYMENT_RESULT",
"payToAmount": {
"currency": "USD",
"value": "11000"
},
"payToId": "*****",
"payToRequestId": "*****",
"paymentAmount": {
"currency": "USD",
"value": "11000"
},
"paymentDetailSummaries": [{
"customerId": "*****",
"customerName": {
"fullName": "******"
},
"extendInfo": "{\"chargeAmount\":\"{\\\"currency\\\":\\\"USD\\\",\\\"value\\\":\\\"33\\\"}\"}",
"paymentAmount": {
"currency": "USD",
"value": "33"
},
"paymentMethodType": "WALLET_WF"
}, {
"customerId": "*****",
"customerName": {
"fullName": "******"
},
"extendInfo": "{}",
"paymentAmount": {
"currency": "USD",
"value": "11000"
},
"paymentMethodType": "WALLET_WF"
}],
"paymentId": "*****",
"paymentTime": "2022-07-18T17:38:04+08:00",
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}
响应
{
"result":{
"resultCode":"SUCCESS",
"resultMessage":"success.",
"resultStatus":"S"
}
}