# 回调服务
TripLink支持在多个业务场景回调客户接口，客户可以在回调接口实现自己的业务逻辑。
回调基于HTTP/HTTPS协议的POST方法，所有请求体都是JSON格式，所有字符都使用UTF-8编码。
回调过程发生如下情况均视为失败：请求失败；请求超时；响应状态码非2XX。
回调分为同步与异步，同步请求必须及时响应，没有重试机制；异步请求无需及时响应，存在重试机制。
# 回调列表
| 名称 | 方式 | 响应时间 | 重试次数 | 重试间隔 |
|---|---|---|---|---|
| 授权决策回调 | 同步 | 3s | N/A | N/A |
| 授权结果通知 | 异步 | 9s | 20 | N × 2min |
| 充值结果通知 | 异步 | 9s | 20 | N × 2min |
# 授权决策回调
TripLink在批准授权请求之前回调此客户接口，客户可以以此实现自己的风控和授权决策。
回调失败则会降级，即TripLink会为客户使用的默认决策结果，参考回调参数。
连续失败10次后系统会不再请求客户接口，直接降级，客户需手动再次开启。
# 请求体
| 名称 | 类型 | 描述 | 备注 |
|---|---|---|---|
bizContent | String | 实际报文 | 需要通过JSON反序列化。详见 AuthorizationDecision。 |
sign | String | 签名 | 对bizContent原文签名，验签RSA公钥同API。详见准备工作。 |
AuthorizationDecision
| 名称 | 类型 | 描述 | 备注 |
|---|---|---|---|
authId | String | 交易唯一ID | 全局唯一。 |
transactionId | String | 交易ID | 授权交易与对应冲正交易的transactionId相同。 |
cardLogId | String | 卡ID | TripLink专用卡标识。 |
localDate | String | 交易当地日期 | 当地时区，格式yyyyMMdd。 |
localTime | Sreing | 交易当地时间 | 当地时区，格式HHmmss。 |
occurTime | String | 交易发生时间 | 卡时区，格式yyyy-MM-dd HH:mm:ss。 |
messageType | String | 交易类型 | 枚举值，4位数字，详见授权类型下拉框。 |
messageTypeDesc | String | 交易类型描述 | 详见授权类型下拉框。 |
transCurrency | String | 交易币种 | ISO 4217货币编号，3位数字。 |
transCurrencyAmt | String | 交易金额 | 小数，对应交易币种。 |
localCurrency | String | 卡币种 | ISO 4217货币编号，3位数字。 |
localCurrencyAmt | String | 卡交易金额 | 小数，对应卡币种。 退款交易卡交易金额为0 |
cardAvailableBalance | String | 卡可用余额 | 小数，对应卡币种。 |
merchantId | String | 商户ID | |
merchantName | String | 商户名称 | |
merchantCategoryCode | String | 商户MCC | ISO 18245商户类别，4位数字。 |
merchantCountry | String | 商户所在国家 | （未标准化） |
isoMerchantCountryCode | String | 商户所在国家 | ISO 3166国家代码，3位字母。参考ISO 3166。 （可能为空值） |
merchantCity | String | 商户所在城市 | |
acquirerId | String | 收单行ID | |
useRef1Txt | String | 用户自定义字段1 | |
useRef2Txt | String | 用户自定义字段2 | |
useRef3Txt | String | 用户自定义字段3 | |
useRef4Txt | String | 用户自定义字段4 | |
useRef5Txt | String | 用户自定义字段5 |
授权类型
| messageType | messageTypeDesc | 描述 |
|---|---|---|
6810 | Authorization Approval | 消费授权 |
6510 | Auth Refund Approval | 退款授权 |
6820 | Authorization Query | 授权查询 |
请求体示例
{
"bizContent": "{\"authId\":\"311503c7-0466-4d01-a500-551c40b91cf6\",\"cardLogId\":\"51a50ffbbd0437ff10fffb93d1620e213441a30a3fa16164d57d98cade066ba0\",\"localTime\":\"025900\",\"localDate\":\"20220623\",\"occurTime\":\"2022-06-23 10:59:00\",\"merchantCategoryCode\":\"0011\",\"merchantName\":\"\",\"merchantCountry\":\"\",\"state\":\"\",\"merchantCity\":\"\",\"messageType\":\"6810\",\"messageTypeDesc\":\"Authorization Approval\",\"acquirerId\":\"213457\",\"merchantId\":\"080000100003\",\"transCurrency\":\"840\",\"transCurrencyAmt\":\"55.66\",\"localCurrency\":\"840\",\"localCurrencyAmt\":\"55.66\",\"useRef1Txt\":\"anything\",\"useRef2Txt\":\"\",\"useRef3Txt\":\"\",\"useRef4Txt\":\"\",\"useRef5Txt\":\"\",\"cardAvailableBalance\":\"955.57\"}",
"sign": "k2/HGZOYIFnYI+WZwW1R1YYryOmYd6ds5rAoioKstfslmeBJvVo1KkPOr5zMt86uZ9XFqJV1vDvavreClLnTBbALvtuF44JLZQsGngMe4MvKcWM2oJX4cCcqptqXkz7XpgCuSST0HeTJ8EHuAIQuF+W87/u86pcUMCBjDus1NuNf5MbS/y/eMW3qCwA5s6q1sp7AR2zmXna+eI+n+JEc9tylxo14Kr17pLGX0NRx+iwuw4H/tnazGDN49vW3kbFzRhj/jxN4vB2rvWIdrL1/pdhI2wFRt5b8AfIwhv5ae0GxP3AuaRCNU3LL+YvkvdIA2o+7RctkGhlbe4upzYARog=="
}
1
2
3
4
2
3
4
# 响应体
客户必须通过响应体中的code字段标识授权决策结果：0：授权通过；非0：授权拒绝。
| 名称 | 类型 | 必填 | 描述 | 备注 |
|---|---|---|---|---|
code | String | Y | 结果码 | 0：授权通过；非0：授权拒绝。 |
msg | String | N | 结果码描述 |
响应体示例
{
"code": "0",
"msg": "success"
}
1
2
3
4
2
3
4
# 授权结果通知
TripLink会在授权完成后以异步的方式发送授权结果至此客户接口。
通知失败会重试，重试次数达上限后不再发送本条通知，其他通知不影响。
# 请求体
| 名称 | 类型 | 描述 | 备注 |
|---|---|---|---|
noticeType | String | 通知类型 | auth。 |
bizContent | String | 实际报文 | 需要通过JSON反序列化。详见 AuthorizationNotification。 |
sign | String | 签名 | 对bizContent原文签名，验签RSA公钥同API。详见准备工作。 |
AuthorizationNotification
| 名称 | 类型 | 描述 | 备注 |
|---|---|---|---|
authId | String | 交易唯一ID | 全局唯一。 |
transactionId | String | 交易ID | 授权交易与对应冲正交易的transactionId相同。 |
cardLogId | String | 卡ID | TripLink专用卡标识。 |
occurTime | String | 交易发生时间 | 卡时区，格式yyyy-MM-dd HH:mm:ss。 |
messageType | String | 交易类型 | 枚举值，4位数字，详见授权类型下拉框。 |
messageTypeDesc | String | 交易类型描述 | 详见授权类型下拉框。 |
reversalType | String | 冲正类型 | 仅授权类型为6930或6940时有值。0：系统冲正；1：非系统冲正。 |
respCode | String | 交易响应码 | 枚举值，4位数字，详见授权响应码下拉框。 |
respCodeDesc | String | 交易响应码描述 | 详见授权响应码下拉框。 |
approveCode | String | 授权码 | 随机6位数字。 |
transCurrency | String | 交易币种 | ISO 4217货币编号，3位数字。 |
transCurrencyAmt | String | 交易金额 | 小数，对应交易币种。 |
localCurrency | String | 卡币种 | ISO 4217货币编号，3位数字。 |
localCurrencyAmt | String | 卡交易金额 | 小数，对应卡币种。 |
cardAvailableBalance | String | 卡可用余额 | 小数，对应卡币种。 |
merchantId | String | 商户ID | |
merchantName | String | 商户名称 | |
merchantCategoryCode | String | 商户MCC | ISO 18245商户类别，4位数字。 |
merchantCountry | String | 商户所在国家 | （未标准化） |
isoMerchantCountryCode | String | 商户所在国家 | ISO 3166国家代码，3位字母。参考ISO 3166。 （可能为空值） |
merchantCity | String | 商户所在城市 | |
acquirerId | String | 收单行ID | |
crossBorderType | String | 交易是否跨境 | 0：境内；1：境外。 |
useRef1Txt | String | 用户自定义字段1 | |
useRef2Txt | String | 用户自定义字段2 | |
useRef3Txt | String | 用户自定义字段3 | |
useRef4Txt | String | 用户自定义字段4 | |
useRef5Txt | String | 用户自定义字段5 |
授权类型
| messageType | messageTypeDesc | 描述 |
|---|---|---|
6810 | Authorization Approval | 消费授权（通过） |
6890 | Authorization Decline | 消费授权（拒绝） |
6510 | Auth Refund Approval | 退款授权（通过） |
6590 | Auth Refund Decline | 退款授权（拒绝） |
6930 | Authorization Reversal Approval | 消费授权冲正 |
6940 | Auth Refund Reversal Approval | 退款授权冲正 |
6820 | Authorization Query | 授权查询 |
授权响应码（6810 消费授权（通过））
| respCode | respCodeDesc | 备注 |
|---|---|---|
0000 | Authorization Approval | 授权成功。 |
授权响应码（6890 消费授权（拒绝））
| respCode | respCodeDesc | 备注 |
|---|---|---|
1002 | High Risk Transaction | 高风险的交易。 |
1003 | Invalid Account | 无效账号。 |
1101 | Abnormal Customer Status | 客户状态异常。 |
1102 | Card canceled | 卡片已注销。 |
1103 | Authorization Amount Error | 授权金额错误。 |
1104 | VAN Amount Limit Error | 账户余额不足。 |
1105 | Invalid Expiry Date | 无效的有效期。 |
1106 | Transaction Count Over Limit | 交易次数超过上限。 |
1107 | Invalid CVV2 | 无效的CVV2安全码。 |
1108 | VAN Amount Limit Error | 账户余额不足。 |
1110 | Trans Currency Not Allowed | 交易币种不支持。 |
1111 | MCC Error | MCC商户类别错误。 |
1112 | VAN credit limit greater than max Limit | 卡片授权金额超出最高限额。 |
1113 | VAN credit limit less than min Limit | 卡片授权金额低于最小限额。 |
1114 | Transaction Date before card activeDate | 交易日期早于卡片有效期。 |
1115 | Transaction Date after card inactiveDate | 交易日期晚于卡片失效日期。 |
1116 | Auth Amount greater than available VAN credit limit | 授权金额超出卡片可用余额。 |
1117 | Auth Amount greater than available account credit limit | 授权金额超出账户可用余额。 |
1118 | Limited usage with abnormal card status | 卡片状态异常暂不可用。 |
1201 | Authorization already in process, please wait until the last authorization completed | 授权过于频繁。 |
1203 | Not support 3ds | 卡不支持3DS交易。 |
2012 | Cardholder cancels identity verification | 持卡人取消身份验证。 |
2014 | Cardholder fails to complete identity verification within the specified time | 持卡人未能在规定时间内完成身份验证。 |
2019 | Cardholder fails to complete identity verification within the specified number of attempts | 持卡人未能在规定的尝试次数内完成身份验证。 |
2022 | Merchant requests invalid information | 商户请求信息不合法。 |
2222 | Authorization decision reject | 授权决策拒绝。 |
2299 | Authorization decision downgrade reject | 授权决策降级后拒绝。 |
3004 | Abnormal Card Scheme Network | 卡组网络异常。 |
9000 | Unknow Error | 未知的错误。 |
授权响应码（6510 退款授权（通过））
| respCode | respCodeDesc | 备注 |
|---|---|---|
0000 | Authorization Approval | 授权成功。 |
授权响应码（6590 退款授权（拒绝））
| respCode | respCodeDesc | 备注 |
|---|---|---|
1002 | High Risk Transaction | 高风险的交易。 |
1003 | Invalid Account | 无效账号。 |
1101 | Abnormal Customer Status | 客户状态异常。 |
1107 | Invalid CVV2 | 无效的CVV2安全码。 |
1110 | Trans Currency Not Allowed | 交易币种不支持。 |
1111 | MCC Error | MCC商户类别错误。 |
授权响应码（6930 消费授权冲正）
| respCode | respCodeDesc | 备注 |
|---|---|---|
0000 | Authorization Approval | 授权成功。 |
1002 | High Risk Transaction | 高风险的交易。 |
1003 | Invalid Account | 无效账号。 |
1101 | Abnormal Customer Status | 客户状态异常。 |
1105 | Invalid Expiry Date | 无效的有效期。 |
2001 | Original Transaction Unmatch | 未匹配到原始的授权交易（有冲正通知）。 |
2002 | Original Transaction Unmatch | 未匹配到原始的授权交易（无冲正通知）。 |
授权响应码（6940 退款授权冲正）
| respCode | respCodeDesc | 备注 |
|---|---|---|
0000 | Authorization Approval | 授权成功。 |
1002 | High Risk Transaction | 高风险的交易。 |
1003 | Invalid Account | 无效账号。 |
2001 | Original Transaction Unmatch | 未匹配到原始的授权交易（有冲正通知）。 |
2002 | Original Transaction Unmatch | 未匹配到原始的授权交易（无冲正通知）。 |
授权响应码（6820 授权查询）
| respCode | respCodeDesc | 备注 |
|---|---|---|
0000 | Authorization Approval | 授权成功。 |
1002 | High Risk Transaction | 高风险的交易。 |
1003 | Invalid Account | 无效账号。 |
1102 | Card canceled | 卡片已注销。 |
1118 | Limited usage with abnormal card status | 卡片状态异常暂不可用。 |
请求体示例
{
"noticeType": "auth",
"bizContent": "{\"customerId\":\"CSR47184A93E35E4\",\"authId\":\"7f1e58b6-e1da-4647-9054-0c1e5b85df4a\",\"cardLogId\":\"51a50ffbbd0437ff10fffb93d1620e213441a30a3fa16164d57d98cade066ba0\",\"cardAvailableBalance\":\"955.57\",\"occurTime\":\"2022-06-23 14:52:35\",\"transCurrency\":\"840\",\"transCurrencyAmt\":\"44.55\",\"localCurrency\":\"840\",\"localCurrencyAmt\":\"44.55\",\"respCode\":\"0000\",\"respCodeDesc\":\"Authorization Approval\",\"approveCode\":\"164913\",\"messageType\":\"6810\",\"messageTypeDesc\":\"Authorization Approval\",\"useRef1Txt\":\"anything\",\"merchantName\":\"\",\"merchantCategoryCode\":\"0011\",\"merchantId\":\"080000100003\",\"merchantCountry\":\"\",\"merchantCity\":\"\",\"merchantPostcode\":\"\",\"acquirerId\":\"213457\",\"state\":\"\"}",
"sign": "raqtzxjjWGyjrPDkn3aR+N+ZU6kpyiLeJNeFzQXmfoqsomkxsccg783FraLPWBrPgn0nhjtuVQLIWMply1chS7g1jgdGaFiGSXCwgL+XIVX0n2J1Z8YtDBEqeJLbRcmWiGAavQk8JSjBtDigJIopjL5mAT9+X5vrf4a6YxpAoky7DemuClKNb50OuH15ADICWednwQZsI0wJ8WTpZNb4f9jrMGdlztXvj/Nf7Gk2Uwx1v/morWEDe1BFD8FWFUsmKwdBxYS8iMT3f5YiAWzYt7VItOl6ymlNSdZmGazXYQ2MPScunPQXdSf2fQ6NM8NVlz7or5w5cj7aiZAgzpHUrQ=="
}
1
2
3
4
5
2
3
4
5
# 响应体
客户必须通过响应体中的code字段标识通知接收结果：0：接收成功；非0：接收失败。
| 名称 | 类型 | 必填 | 描述 | 备注 |
|---|---|---|---|---|
code | String | Y | 结果码 | 0：接收成功；非0：接收失败。 |
msg | String | N | 结果码描述 |
响应体示例
{
"code": "0",
"msg": "success"
}
1
2
3
4
2
3
4
# 充值结果通知
TripLink会在充值完成后以异步的方式发送充值结果至此客户接口。
通知失败会重试，重试次数达上限后不再发送本条通知，其他通知不影响。
# 请求体
| 名称 | 类型 | 描述 | 备注 |
|---|---|---|---|
noticeType | String | 通知类型 | deposit。 |
bizContent | String | 实际报文 | 需要通过JSON反序列化。详见 DepositNotification。 |
sign | String | 签名 | 对bizContent原文签名，验签RSA公钥同API。详见准备工作。 |
DepositNotification
| 名称 | 类型 | 描述 | 备注 |
|---|---|---|---|
orderId | String | TripLink内部订单号 | 全局唯一。 |
orderType | String | 订单类型 | Topup。 |
creditAccountNo | String | 贷方账号 | |
creditAccountName | String | 贷方账户名 | |
debitAccountNo | String | 借方账号 | |
debitAccountName | String | 借方账户名 | |
currency | String | 币种 | ISO 4217货币编号，3位字母。 |
amount | String | 金额 | |
transactionTime | String | 交易时间 | 格式yyyy-MM-dd HH:mm:ss。 |
remark | String | 备注 |
请求体示例
{
"noticeType": "deposit",
"bizContent": "{\"orderId\":\"102208011748082999\",\"orderType\":\"Topup\",\"creditAccountNo\":\"6300156327\",\"creditAccountName\":\"123wzy\",\"debitAccontNo\":\"623046407891010\",\"debitAccountName\":\"XX银行\",\"currency\":\"HKD\",\"amount\":\"1.00\",\"transactionTime\":\"2022-08-01 17:49:30\",\"remark\":\"FT202107007100221615\"}",
"sign": "J4079QgEUJdqZtx/9/L8m2ZCEcs/18un2w+vL9SNmM7EaxrWX3lEA6CObv3FLpRNKadtkdekCavy0MK3tL+vb95MAX7nDQakeYhBk0oVfIyQYhYCtskxSHFy9ZO+Ys8f2MCbPNwl489SnrskXOE0Azxvtsk22C6GmWuRMA4gbO7xoneg/lMlxyiu/mVkoHZ8E1bBQBdYK0G14M/XzU/Xchn6VzPCydW9t7+epVEKgz3dO9qKJk6Gz1P/3ui+s84gWn1jUToaHR23BGjEg9wZln1K/1x5CF6/kUjHhSfq1bAvD5ctsajKvYTaspv65dVh7untNLl5K1WAI7EZ1YFGog=="
}
1
2
3
4
5
2
3
4
5
# 响应体
客户必须通过响应体中的code字段标识通知接收结果：0：接收成功；非0：接收失败。
| 名称 | 类型 | 必填 | 描述 | 备注 |
|---|---|---|---|---|
code | String | Y | 结果码 | 0：接收成功；非0：接收失败。 |
msg | String | N | 结果码描述 |
响应体示例
{
"code": "0",
"msg": "success"
}
1
2
3
4
2
3
4
# 结果通知查询与重发
客户可以在商户系统（交易管理 - 通知查询）查询所有结果通知，并支持重发（单条/批量）。
# SDK验签示例
Java SDK
public void rsaVerify() {
String bizContent = "{\"customerId\":\"CSR47184A93E35E4\",\"authId\":\"07c93b59-23b2-4aa0-8cff-55a026b02329\",\"cardLogId\":\"42f4d634e184351e6b035eb58ea4892620ce2eaa5347fcd206646fe24ffae905\",\"cardAvailableBalance\":\"966.68\",\"occurTime\":\"2022-06-23 14:06:36\",\"transCurrency\":\"840\",\"transCurrencyAmt\":\"33.44\",\"localCurrency\":\"840\",\"localCurrencyAmt\":\"33.44\",\"respCode\":\"0000\",\"respCodeDesc\":\"Authorization Approval\",\"approveCode\":\"057685\",\"messageType\":\"6810\",\"messageTypeDesc\":\"Authorization Approval\",\"useRef1Txt\":\"anything\",\"merchantName\":\"\",\"merchantCategoryCode\":\"0011\",\"merchantId\":\"080000100003\",\"merchantCountry\":\"\",\"merchantCity\":\"\",\"merchantPostcode\":\"\",\"acquirerId\":\"213457\",\"state\":\"\"}";
String sign = "tNNvnZBcvb7IR4qkPM9j+5/Hun1qj7MlnmcqeLKAO0Q8R4EB2OYLPTf/q50Rlq/gJf5x93OWSbSg9QqhktgZM0abZIKoAnidzNdGoLdINPSfdhkB/bkrpC8LctqEsLXwU2Kn3LHK3qAgDDJAf5AGmZmzn9SXnO2tvdVMvLbSj8vACpMm12g/zQyUPJ5NlCI7Hf5DXQeQy/Hd0hSyAFuhHO/V++a4TdEDZ3wqh9a1JVs0cy7t63vI0IT6r6l6hjiInoahW7H/zVZ1jcdhxNc1hGJRaM6GvlwsSFH9+gqIYv/DIPxIqTP2Bk6IDc0JaPBx/ClH7mefkunRerzCXFKC+g==";
boolean verified = CipherUtils.rsaVerify(TRIPLINK_PUBLIC_KEY, bizContent, sign);
Assert.assertTrue(verified);
}
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
PHP SDK
public function testRsaVerify(): void {
$bizContent = '{"customerId":"CSR47184A93E35E4","authId":"07c93b59-23b2-4aa0-8cff-55a026b02329","cardLogId":"42f4d634e184351e6b035eb58ea4892620ce2eaa5347fcd206646fe24ffae905","cardAvailableBalance":"966.68","occurTime":"2022-06-23 14:06:36","transCurrency":"840","transCurrencyAmt":"33.44","localCurrency":"840","localCurrencyAmt":"33.44","respCode":"0000","respCodeDesc":"Authorization Approval","approveCode":"057685","messageType":"6810","messageTypeDesc":"Authorization Approval","useRef1Txt":"anything","merchantName":"","merchantCategoryCode":"0011","merchantId":"080000100003","merchantCountry":"","merchantCity":"","merchantPostcode":"","acquirerId":"213457","state":""}';
$sign = 'tNNvnZBcvb7IR4qkPM9j+5/Hun1qj7MlnmcqeLKAO0Q8R4EB2OYLPTf/q50Rlq/gJf5x93OWSbSg9QqhktgZM0abZIKoAnidzNdGoLdINPSfdhkB/bkrpC8LctqEsLXwU2Kn3LHK3qAgDDJAf5AGmZmzn9SXnO2tvdVMvLbSj8vACpMm12g/zQyUPJ5NlCI7Hf5DXQeQy/Hd0hSyAFuhHO/V++a4TdEDZ3wqh9a1JVs0cy7t63vI0IT6r6l6hjiInoahW7H/zVZ1jcdhxNc1hGJRaM6GvlwsSFH9+gqIYv/DIPxIqTP2Bk6IDc0JaPBx/ClH7mefkunRerzCXFKC+g==';
$verified = CipherUtils::rsaVerify(TRIPLINK_PUBLIC_KEY, $bizContent, $sign);
$this->assertTrue($verified);
}
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
TRIPLINK_PUBLIC_KEY：TripLink RSA公钥。