notifyTransfer

2023-06-09 10:01

需要签名验签

万里汇使用此API向集成商发送转账代发结果通知。集成商可在调用 createTransfer 接口时传入 transferToDetail.transferNotifyUrl 设置接收通知的地址。

集成商在收到通知后需正确发送响应。

接口结构

万里汇接口报文结构包括：请求头，请求体。

请求头

字段名	是否必传	范例	说明
Client-Id	是	Client-Id: *****	关于这些参数的解释说明，详见：请求头
Signature	是	Signature: algorithm=RSA256, keyVersion=2, signature=*****
Content-Type	是	Content-Type: application/json; charset=UTF-8
Request-Time	是	Request-Time: 2019-04-04T12:08:56+08:00

请求参数

字段名	数据类型	是否必传	描述
transferRequestId	字符串	是	由集成商定义的唯一转账代发识别ID。更多信息：此字段为幂等字段字段最大长度：64
transferId	字符串	是	由万里汇定义的转账代发识别ID。更多信息：字段最大长度：64
transferResult	Result 对象	是	代表转账代发结果。
transferFinishTime	字符串(Datetime)	是	本次转账代发请求的结束时间。更多信息：此字段采用ISO 8601 标准时间戳。如：`2018-09-03T00:00:00+08:00`，或`2019-01-01T01:01:01Z`（UTC时间）
transferFromDetail	TransferFromDetail 对象	是	支付方的转账代发请求细节。
transferToDetail	TransferToDetail 对象	是	收款方的转账代发请求细节，包括收款方所收到的转账金额等。
transferOrderAddition	TransferOrderAddition 对象	否	转账代发的更多信息，包括支付方和收款方的信息等。

请求处理

transferResult.result：此字段为转账代发结果。更多详见：结果码

在收到万里汇的请求之后，集成商需要向万里汇发送响应信息，以确认信息已收到。

发送响应信息前，集成商需正确加签。详见：生成签名及加验签章节。

头信息包括：

响应头参数	是否必传	范例
Signature	是	Signature: algorithm=RSA256, keyVersion=2, signature=****
Content-Type	是	Content-Type: application/json; charset=UTF-8
Client-Id	是	Client-Id: ****
Response-Time	是	Response-Time: 2019-04-04T12:08:56+08:00

范例响应体：

copy
{
  "result":{
     "resultStatus":"S",
     "resultCode":"SUCCESS",
     "resultMessage":"success"
  }
}

更多关于响应信息，参考：API概览-响应报文结构

如果集成商不向万里汇发送响应信息，万里汇会重新发送请求通知。万里汇重发通知的规则为：

重试总数：7次
两次重发请求之间的间隔：2分钟，10分钟，10分钟，1小时，2小时，6小时，15小时

响应参数

字段名	数据类型	是否为必填字段	描述
result	Result 对象	是	代表接口调用结果

结果码

`result.resultCode`

系统结果码

resultCode	resultStatus	resultMessage	处理建议
SUCCESS	S	Success
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.	参考API文档页面，确认请求头和传参是否正确
PROCESS_FAIL	F	A general business failure occurred. Do not retry.	需要人工介入，联系万里汇技术支持以解决此问题
UNKNOWN_EXCEPTION	U	API failed due to unknown reason.	服务器错误，若稍后重试问题依旧，联系万里汇技术支持以解决问题
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	重试，若问题依旧，联系万里汇技术支持
INVALID_API	F	The called API is invalid or not active.	确认是否调用正确的API
INVALID_CLIENT	F	The client is invalid.	Client ID不存在或无效
INVALID_SIGNATURE	F	The signature is invalid.	确认请求正确加签
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.	确认HTTP请求方法为`POST`

`transferResult.resultCode`

resultCode	resultStatus	resultMessage	处理建议
SUCCESS	S	Success
PROCESS_FAIL	F	A general business failure occurred. Do not retry.	需要人工介入，联系万里汇技术支持以解决此问题
USER_NOT_EXIST	F	The user does not exist.	使用正确的用户信息重试
USER_ACCOUNT_ABNORMAL	F	The user account status is abnormal.	使用其他用户信息重试。如问题依旧，看戏万里汇技术支持
AMOUNT_EXCEED_LIMIT	F	The amount exceeds the limit.	确认金额正确后重试
RISK_REJECT	F	The transfer is rejected for risk control reasons.	通知用户需要通过风控审核
ORDER_IS_CLOSED	F	The order is closed.	换单重试
ORDER_IS_REVERSED	F	The order is reversed.	换单重试
CARD_INFO_NOT_MATCH	F	The card information does not match.	换卡重试
BALANCE_NOT_ENOUGH	F	Balance is not enough.	确认余额充足后重试

范例

请求体范例

copy
{
    "transferResult": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    },
    "transferRequestId": "*****",
    "transferId": "*****",
    "transferFinishTime": "2022-05-11T06:27:25Z",
    "transferFromDetail": {
        "transferFromAmount": {
            "currency": "USD",
            "value": 1000
        }
    },
    "transferToDetail": {
        "purposeCode": "GDS",
        "transferToAmount": {
            "currency": "EUR",
            "value": 938
        },
        "feeAmount": {
            "currency": "USD",
            "value": 10
        },
        "transferToMethod": {
            "customerId": "*****",
            "paymentMethodType": "BALANCE"
        },
        "transferQuote": {
            "quoteId": "*****"
        }
    },
    "transferOrderAddition": {
        "referenceOrderId": "*****"
    }
}

响应体范例

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    }
}