notifyPayout

2023-06-09 10:01

需要签名验签

万里汇使用此API向集成商发送转账到卡结果通知。集成商可在调用 createPayout 接口时传入 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

请求参数

字段名	数据类型	是否必传	描述
transferResult	Result 对象	否	表明交易请求结果。
transferRequestId	字符串	否	由集成商定义、用于唯一标识某交易请求。更多信息：本字段为API的幂等字段，具体详见幂等字段介绍。字段最大长度：64
transferId	字符串	否	由万里汇定义、用于唯一标识某交易。更多信息：字段最大长度：64
transferFinishTime	字符串 (Datetime)	否	表明交易结束的时间点。更多信息：此字段采用ISO 8601 标准时间戳。如：`2018-09-03T00:00:00+08:00`，或`2019-01-01T01:01:01Z`（UTC时间）
transferFromDetail	TransferFromDetail 对象	否	由付款人发起的交易金额。
transferToDetail	TransferToDetail 对象	否	有关收款人的交易详情，如收款人接收的交易金额。
transferOrderAddition	TransferOrderAddition 对象	否	有关交易的其它信息，如付款人和收款人的信息。

请求处理

transferResult.resultCode：此字段为转账到卡结果。

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

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

头信息包括：

响应头参数	是否必填	范例
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
UNKNOWN_EXCEPTION	U	API failed due to unknown reason.	服务器错误，若稍后重试问题依旧，联系万里汇技术支持以解决问题
PROCESS_FAIL	F	A general business failure occurred. Do not retry.	需要人工介入，联系万里汇技术支持以解决此问题

`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.	确认余额充足后重试

范例

请求

请求体范例-场景1

copy
{
    "transferResult": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    },
    "transferRequestId": "*****",
    "transferId": "*****",
    "transferFromDetail": {
        "transferFromAmount": {
            "currency": "USD",
            "value": 1000
        }
    },
    "transferToDetail": {
        "purposeCode": "GDS",
        "transferToAmount": {
            "currency": "EUR",
            "value": 938
        },
        "feeAmount": {
            "currency": "USD",
            "value": 10
        },
        "transferToMethod": {
            "paymentMethodId": "*****",
            "paymentMethodType": "BANK_ACCOUNT_DETAIL"
        },
        "transferQuote": {
            "quoteId": "*****"
        },
        "transferMemo": "memo shows in worldfirst statement",
        "transferRemark": "remark shows in bank statement"
    },
    "transferOrderAddition": {
        "referenceOrderId": "*****"
    }
}

请求体范例-场景2

copy
{
    "transferResult": {
        "resultCode": "ORDER_IS_REVERSED",
        "resultMessage": "The order is reversed.",
        "resultStatus": "F"
    },
    "transferRequestId": "*****",
    "transferId": "*****",
    "transferFromDetail": {
        "transferFromAmount": {
            "currency": "USD",
            "value": 1000
        }
    },
    "transferToDetail": {
        "purposeCode": "GDS",
        "transferToAmount": {
            "currency": "EUR",
            "value": 938
        },
        "feeAmount": {
            "currency": "USD",
            "value": 10
        },
        "transferToReturnAmount": {
            "currency": "EUR",
            "value": 918
        },
        "transferToMethod": {
            "paymentMethodId": "*****",
            "paymentMethodType": "BANK_ACCOUNT_DETAIL"
        },
        "transferQuote": {
            "quoteId": "*****"
        },
        "transferMemo": "memo shows in worldfirst statement",
        "transferRemark": "remark shows in bank statement"
    },
    "transferOrderAddition": {
        "referenceOrderId": "*****"
    }
}

响应

响应头范例

copy
{
"headers": {
  "Content-Type": "application/json",
  "client-id": "*****",
  "response-time": "2022-03-07T07:49:27Z",
  "signature": "algorithm=RSA256,keyVersion=1,signature=abc*****"
  }
}

响应体范例

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