# 回调服务

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

# 响应体

客户必须通过响应体中的code字段标识授权决策结果:0:授权通过;非0:授权拒绝。

名称 类型 必填 描述 备注
code String Y 结果码 0:授权通过;非0:授权拒绝。
msg String N 结果码描述
响应体示例
{
  "code": "0",
  "msg": "success"
}
1
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 冲正类型 授权类型69306940时有值。
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

# 响应体

客户必须通过响应体中的code字段标识通知接收结果:0:接收成功;非0:接收失败。

名称 类型 必填 描述 备注
code String Y 结果码 0:接收成功;非0:接收失败。
msg String N 结果码描述
响应体示例
{
  "code": "0",
  "msg": "success"
}
1
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

# 响应体

客户必须通过响应体中的code字段标识通知接收结果:0:接收成功;非0:接收失败。

名称 类型 必填 描述 备注
code String Y 结果码 0:接收成功;非0:接收失败。
msg String N 结果码描述
响应体示例
{
  "code": "0",
  "msg": "success"
}
1
2
3
4

# 结果通知查询与重发

客户可以在商户系统(交易管理 - 通知查询)查询所有结果通知,并支持重发(单条/批量)。

Config Submit

# 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
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

TRIPLINK_PUBLIC_KEY:TripLink RSA公钥。