20.WEBHOOK

我方会给商户在商户后台【设置】>【密钥管理】中配置的回调地址推送信息

推送有以下几种以dataType区分：

1.卡片发生授权交易后通知；

2.卡片清算信息通知；

3.销卡发起通知（用于客户过滤后单独处理非自己发起的销卡订单）；

4.账户退款（销卡后退款）通知（用户客户处理补入账）；

5.订单状态终态通知(仅限于订单类型：开卡、卡充值、卡退款、销卡；卡组申请、卡组充值、卡组退款、卡组注销)。

失败会重试 11次，时间覆盖24小时。商户接到通知并返回 ok 视为通知成功。

响应结果

序号	字段	字段描述	字段类型	必填	备注
1	dataType	数据类型	String	必填	AUTH-交易，SETTLEMENT-清算， TYPE_CARD_OPERATE-卡操作 ACCOUNT_REFUND 账户退款（销卡后退款） ORDER_NOTIFY卡片订单终态CARD_3DS_NOTIFY 3DS卡通知ACCOUNT_DETAIL 账户详情, CARD_BIND_CODE_NOTIFY绑卡通知
2	request	通知内容	String	必填	加密内容

响应示例

{
  "dataType": "AUTH",
  "request": "234rfde567uhgdw45678ijhgjhde",
}

1.交易结果通知

request (dataType=AUTH) 交易解密后内容

{
  "recordNo": "221101...0000001",
  "cardId": "221...0000001",
  "occurTime": "2022-11-01 14:39:19",
  "transCurrency": "USD",
  "transCurrencyAmt": 10.00,
  "transType": "AUTH",
  "transStatus": "APPROVED",
  "localCurrency": "USD",
  "localCurrencyAmt": 10.00,
  "crossBoardType": null,
  "respCode": "000000",
  "respCodeDesc": "交易成功",
  "approvalCode": "000000",
  "merchantName": "xxxxx...xxxxx",
  "merchantCategoryCode": "5881",
  "commissionForRecordNo": 14231...472276b
}

Result:

序号	字段	字段描述	字段类型	必填	备注
1	recordNo	记录编号	String	必填
2	cardId	卡唯一编号	String	必填
3	occurTime	交易发生时间	String	必填
4	transCurrency	交易币种	String	/
5	transCurrencyAmt	交易币种金额	Number	必填
6	transType	交易类型	String	必填	（20221211新增） 交易类型: 见交易类型列表
7	transStatus	交易状态	String	必填	（20221211新增） 交易状态: 见交易状态列表
8	localCurrency	卡本币种	String	必填
9	localCurrencyAmt	卡本币种金额	Number	必填
10	crossBoardType	跨境类型	String	/	（20221211新增） 0 境内；1 境外
11	respCode	交易响应码	String	必填	见交易响应码
12	respCodeDesc	交易响应码描述	String	必填
13	approvalCode	授权码	String	/
14	merchantName	商户名称	String	/
15	merchantCategoryCode	商户MCC	String	/	MCC，消费场景行业类型
16	commissionForRecordNo	关联transType为AUTH的recordNo字段	String	/	本字段仅在 transType="TRANS_FEE"（手续费交易）时有效，其值为所对应的原始transType="AUTH"（预授权/授权交易）的主交易记录号 (recordNo)。

2.清算结果通知

request (dataType=SETTLEMENT) 清算解密后内容

{
  "recordNo": "221101...000001",
  "cardId": "221...0000001",
  "settleDate": "2022-11-02",
  "transCurrency": "USD",
  "transCurrencyAmt": 0.00,
  "billCurrency": "USD",
  "billCurrencyAmt": 0.00,
  "approvalCode": "000000",
  "isCredit": "1",
  "merchantName": "xxxxxxxx"
}

Result:

序号	字段	字段描述	字段类型	必填	备注
1	recordNo	记录编号	String	必填	记录编号
2	cardId	卡唯一编号	String	必填	卡片编号
3	settleDate	账单日期	String	必填	账单日期
4	transCurrency	交易币种	String	必填	交易币种
5	transCurrencyAmt	交易金额	Number	必填	交易金额
6	billCurrency	账单币种	String	必填	账单币种
7	billCurrencyAmt	账单金额	Number	必填	账单金额
8	approvalCode	授权码	String	必填	授权码
9	isCredit	收付标志	String	必填	0:付(消费) 1:收(退款) 2:交易处理费
10	merchantName	商户名称	String	/	商户名称

被动销卡发生场景：卡到期、触达使用次数限制、触发风控等。被动销卡时，卡内金额将自动返还主账户。

3.销卡发起通知

request (dataType=TYPE_CARD_OPERATE) 卡操作（当销卡发起后会推送该通知，客户需过滤得到非自行发起的销卡，跟踪后续流程）

{
  "orderNo": "22281...23132123",
  "requestNo": "221...0000001",
  "customerId": "124765...2312312",
  "groupId": "124765...2312312",
  "cardId": "124765...2312312",
  "cardNo": "124765...2312312",
  "orderType": "CARD_CLOSE",
  "orderDate": "2023-05-18T03:42:20.000+0000",
  "tradeDate": "2022-11-29 12:00:00",
  "orderAmount": 100.00,
  "orderStatus": "UNKNOWN"
}

Result:

字段	字段描述	字段类型	必填	备注
orderNo	平台订单号	String	必填
requestNo	客户请求流水号	String	必填
customerId	客户编号	String	必填
groupId	共享卡卡组ID	String	/	订单为共享卡相关时返回
cardId	卡ID	Number	/	订单为卡相关时返回
cardNo	卡号	String	/	订单为卡相关时返回
orderType	订单类型	String	必填	CARD_CLOSE
tradeDate	交易时间	String	必填	yyyy-MM-dd HH:mm:ss
orderAmount	订单金额	Number	必填
orderStatus	订单状态	String	必填	只要发起销卡就会通知(不管shi谁发起)，状态不定，可能是任意订单状态

4.账户退款通知

request (dataType=ACCOUNT_REFUND) 账户退款(销卡后退款)

这种情况出现在卡片退款记录清算时卡片已经销掉的情况，资金无法回卡，会回到商户主账户，并webhook通知

{
  "customerId": "221101...000001",
  "orderNo": "221101...000001",
  "cardId": "221...0000001",
  "currency": "USD",
  "amount": 0.00,
  "createAt": "2023-05-18T03:42:20.000+0000",
  "tradeDate": "2022-11-29 12:00:00"
}

Result:

序号	字段	字段描述	字段类型	必填	备注
1	customerId	客户编号	String	必填
2	orderNo	平台订单号	String	必填	平台订单号
3	cardId	卡唯一编号	String	必填	卡片编号
4	currency	币种	int	必填
5	amount	金额	Number	必填
6	createAt	创建时间	Date	必填	“拟废弃”，请尽量使用tradeDate
7	tradeDate	交易日期	String	必填	yyyy-MM-dd HH:mm:ss

5.订单状态推送

dataType=ORDER_NOTIFY，解密后内容

{
  "orderNo": "22281...23132123",
  "requestNo": "221...0000001",
  "customerId": "124765...2312312",
  "groupId": "124765...2312312",
  "cardId": "124765...2312312",
  "cardNo": "124765...2312312",
  "cardCurrency": "USD",
  "cardCvv": "123",
  "cardExpiryDate": "2022-11",
  "orderType": "GROUP_APPLY",
  "orderDate": "2023-05-18T03:42:20.000+0000",
  "tradeDate": "2022-11-29 12:00:00",
  "orderAmount": 100.00,
  "orderStatus": "SUCCESS"
}

卡操作 Result

字段	字段描述	字段类型	必填	备注
orderNo	平台订单号	String	必填
requestNo	客户请求流水号	String	必填
customerId	客户编号	String	必填
groupId	共享卡卡组ID	String	/	订单为共享卡相关时返回
cardId	卡ID	Number	/	订单为卡相关时返回
cardNo	卡号	String	/	订单为卡相关时返回
cardCurrency	卡币种	Number	/	订单开卡申请相关时返回
cardCvv	卡片CVV	String	/	订单开卡申请相关时返回
cardExpiryDate	失效日期	String	/	订单开卡申请相关时返回
orderType	订单类型	String	必填	开卡：CARD_APPLY、 卡充值：CARD_RECHARGE、 卡退款：CARD_RERUND、销卡：CARD_CLOSE、 被动销卡：CARD_OPERATE、 卡组申请：GROUP_APPLY、 卡组充值：GROUP_RECHARGE、 卡组退款：GROUP_REFUND、 销卡组：GROUP_CLOSE
orderDate	订单日期	Date	必填	“拟废弃”，请尽量使用tradeDate
tradeDate	交易时间	String	必填	yyyy-MM-dd HH:mm:ss
orderAmount	订单金额	Number	必填
orderStatus	订单状态	String	必填	SUCCESS,FAILED,INIT,ACCEPTED,UNKNOWN

响应VCC Webhook 代码示例

@PostMapping("notify")
@ApiOperation(value = "交易内容通知", notes = "交易内容通知")
public String notify(@RequestBody ApiCallbackRequest request) {
    log.info("收到VCC Notify message：======== >> {}", request);
    
    // do something.
    
    return "ok";
}

6.3DS 卡通知接口

dataType=CARD_3DS_NOTIFY

①：接口概述

3DS 卡通知接口可供客户根据自身需求进行相应转发。

②：响应示例

{
  "verificationCode": "126789",
  "transCurrencyAmt": "100.50",
  "transCurrency": "USD",
  "cardNo": "123432532456",
  "time": "2025-08-26 06:12:10",
  "email": "[e-mail]",
  "language": "EN",
  "cardId":"0921......1648618746"
}

③：响应参数

响应为 JSON 格式，各字段说明如下：

字段名	类型	是否必填	说明	示例值
verificationCode	String	是	短信中的验证码，通常为 4-6 位数字	"126789"
transCurrencyAmt	String	是	交易金额，支持小数格式	"100.50"
transCurrency	String	是	货币类型，遵循 ISO 4217 标准（如美元为 USD，欧元为 EUR）	"USD"
cardNo	String	是	卡号	"123432532456"
time	String	是	卡片交易验证码接收时间，格式需为 yyyy-MM-dd HH:mm:ss（UTC+8 时区）	"2025-08-26 06:12:10"
email	String	是	客户电子邮箱地址	"[e-mail]"
language	String	否	客户使用语言，支持 EN（英语）、RU（俄语）、ZH（中文）	"EN"
cardId	String	是	Customer CardId	"092183018092831084671648618746"

④：注意事项

1. time 字段（时间）必须严格遵循 yyyy-MM-dd HH:mm:ss 格式，否则会导致解析失败，请求发送前需检查格式是否正确。

2. 货币字段 transCurrency 需使用 3 位字母的 ISO 4217 标准代码，以确保系统能够识别。

3. 该通知为一次性操作，由于交易存在时效性要求，验证码的有效期较短，若通知发送失败，将不再进行重发。

7. URI_CHECK校验说明

dataType=URI_CHECK

说明：当第一次向该回调地址发起请求后，系统会实时探测并验证其可达性与可用性。

8.ACCOUNT_DETAIL通知说明

dataType=ACCOUNT_DETAIL 账户详情数据通知说明

①：接口概述

当余额账户有更变时(卡充值或者开卡)的时候, 会推送账户更变的详情数据.

②：响应示例

{ 
"customerId": "8819045....288", 
"orderNo": "25102......80938", 
"requestNo": "128738917397....127387198273", 
"cardId": "3b3d1b........77fd1", 
"cardNo": "525.........09540", 
"detailType": "card-recharge", 
"currency": "USD", 
"amount": 2.370000, 
"createdAt": "2025-10-29T14:10:48.000+0000", 
"tradeDate": "2025-10-29 22:10:48" 
}

③：响应参数

响应为 JSON 格式，各字段说明如下：

字段名	类型	是否必填	说明
customerId	String	Y	客户名称
orderNo	String	Y	订单号
requestNo	String	Y	客户请求流水号
cardId	String	Y	系统内的卡编号
cardNo	String	Y	系统内的卡号
detailType	String	Y	详情类型
currency	String	Y	币种
amount	Number	Y	金额
createdAt	String	Y	记录创建时间
tradeDate	String	Y	交易时间

9.CARD_BIND_CODE_NOTIFY通知

dataType=CARD_BIND_CODE_NOTIFY 部分产品绑定Applepay&Googlepay钱包时发送验证码的通知说明

①：接口概述

在卡片绑定 Apple Pay / Google Pay 流程中，系统会触发OTP（一次性验证码）下发流程，用户需提交正确验证码完成校验，绑定流程才可成功。

②：响应示例

{
  "cardId": "d8bae5d....0c4b958d162",
  "cardNo": "525847....38973",
  "time": "2026-03-19 15:51:11",
  "verificationCode": "123456"
}

③：响应参数

响应为 JSON 格式，各字段说明如下：

字段名	类型	是否必填	说明
cardId	String	Y	系统内的卡编号
cardNo	String	Y	系统内的卡号
time	String	Y	通知创建时间
verificationCode	String	Y	验证码,一般是6位数字