通知订阅

请商户提供回调地址。在商户后台中进行配置后才会进行通知。

当交易有最终结果后，通过webhook配置，开发平台会发送交易通知给商户，当接受不成功或者发送失败时， 交易会发7次，时间间隔为1m，5m，20m，1h，12h，24h。

通知模板

Headers

Name	Value
Content-Type	application/json
X-WSB-CATEGORY	${X-WSB-CATEGORY}
X-WSB-SIGNATURE	${signature}
X-WSB-REQUEST-ID	${requestId}

卡交易通知

X-WSB-CATEGORY=card_transaction

通知参数

参数	类型	是否必传	备注
orderNo	String	是	平台订单号
merchantOrderNo	String	否	商户订单号
cardNo	String	否	银行卡id
currency	String	是	币种
amount	BigDecimal	是	金额
fee	BigDecimal	是	手续费
receivedAmount	BigDecimal	否	到账金额
receivedCurrency	String	否	到账币种
type	String	是	类型。 create: 开卡; deposit: 充值; cancel: 销卡; Freeze：冻结； UnFreeze：解冻
status	String	是	状态。 wait_process: 待处理; processing: 处理中; success: 成功; fail: 失败
remark	String	否	交易备注
transactionTime	Long	是	交易时间。毫秒时间戳

通知示例

{
    "orderNo": "1852379830190366720",
    "merchantOrderNo": "T1852379826671345664",
    "cardNo": "23424290324234454242",
    "currency": "USD",
    "amount": "15",
    "fee": "0",
    "receivedAmount": "0",
    "receivedCurrency": "USD",
    "type": "create",
    "status": "success",
    "remark": null,
    "transactionTime": 1730476742000
}

响应

当返回结构体为下方所示时，回调通知成功

200

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": null
}

卡授权交易通知

X-WSB-CATEGORY=card_auth_transaction 同一交易流水号可能存在推送多次。

1. 状态可能会存在流转。比如type=auth时，第一次推送status=authorized（已授权），待授权成功收到结算信息流后将再次推送status=succeed或其他状态。

2. 将会推送结算金额等信息，金额可能会存在变化。比如crossBoardFee、settleAmount会从0变成有值。

通知参数

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
tradeNo	String	是	交易流水号
originTradeNo	String	否	原交易流水号
currency	String	否	交易币种
amount	BigDecimal	否	交易金额
authorizedAmount	BigDecimal	是	授权金额
authorizedCurrency	String	是	授权币种
fee	BigDecimal	是	授权手续费
feeCurrency	String	否	授权手续费币种
crossBoardFee	BigDecimal	是	跨境交易手续费
crossBoardFeeCurrency	String	否	跨境交易手续费币种
settleAmount	BigDecimal	否	结算金额。收到结算信息后推送
settleCurrency	String	否	结算币种。收到结算信息后推送
settleDate	Long	否	结算日期。毫秒时间戳
merchantName	String	是	商户名称
type	String	是	类型。 auth：授权； correct_auth：授权冲正； correct_refund：退款冲正； refund：退款； verification：验证； Void：撤销；
typeStr	String	是	交易类型描述
status	String	是	状态。 authorized：已授权； revoked：已撤销 failed：失败； succeed：成功；
statusStr	String	是	状态描述
description	String	是	交易描述
transactionTime	Long	是	交易时间。毫秒时间戳

通知示例

示例1

{
    "cardNo": "1242352328671924231",
    "tradeNo": "trans1232435363435463432",
    "originTradeNo": null,
    "currency": "CNY",
    "amount": "16.96",
    "authorizedAmount": "2.45",
    "authorizedCurrency": "USD",
    "fee": "0.5",
    "feeCurrency": "USD",
    "crossBoardFee": "0",
    "crossBoardFeeCurrency": null,
    "settleAmount": 0,
    "settleCurrency": null,
    "settleDate": null,
    "merchantName": "ALP*Mr Rice 1223",
    "type": "auth",
    "typeStr": "授权",
    "status": "authorized",
    "statusStr": "已授权",
    "transactionTime": 1729422898000,
    "description": "Auth"
}

示例2

{
    "cardNo": "1242352328671924231",
    "tradeNo": "trans1232435363435463432",
    "originTradeNo": null,
    "currency": "CNY",
    "amount": "16.96",
    "authorizedAmount": "2.45",
    "authorizedCurrency": "USD",
    "fee": "0.5",
    "feeCurrency": "USD",
    "crossBoardFee": "0",
    "crossBoardFeeCurrency": null,
    "settleAmount": "2.45",
    "settleCurrency": "USD",
    "settleDate": 1730995200,
    "merchantName": "ALP*Mr Rice 1223",
    "type": "auth",
    "typeStr": "授权",
    "status": "succeed",
    "statusStr": "成功",
    "transactionTime": 1729422898000,
    "description": "Auth"
}

响应

当返回结构体为下方所示时，回调通知成功

200

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": null
}

卡授权交易冲正通知

X-WSB-CATEGORY=card_fee_patch 如果用户银行卡余额不足扣除手续费，渠道将进行费率冲正。所以如果用户银行卡余额不足，将会对商户在平台中备付金账户进行扣款抵扣。

通知参数

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
tradeNo	String	是	交易流水号
originTradeNo	String	是	原交易流水号。授权交易中的tradeNo
currency	String	是	交易币种
amount	BigDecimal	是	交易金额
type	String	是	card_patch_fee：费率冲正；card_patch_cross_border：跨境手续费冲正； card_patch_settle：结算冲正；
deductionSourceFunds	String	是	资金扣除来源。 wallet：钱包；
status	String	是	状态。 success：成功；
statusStr	String	是	状态描述
transactionTime	Long	是	交易时间。毫秒时间戳

通知示例

{
    "cardNo": "1242352328671924231",
    "tradeNo": "CAF1232435363435463432",
    "originTradeNo": "trans1232435363435463432",
    "currency": "USD",
    "amount": "0.5",
    "type": "card_patch_fee",
    "deductionSourceFunds": "wallet",
    "status": "success",
    "statusStr": "成功",
    "transactionTime": 1729422898000
}

响应

当返回结构体为下方所示时，回调通知成功

200

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": null
}

卡3ds通知

X-WSB-CATEGORY=card_3ds

通知参数

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
tradeNo	String	是	交易流水号
originTradeNo	String	否	原交易流水号
currency	String	是	交易币种
amount	BigDecimal	是	交易金额
merchantName	String	是	商户名称（交易场景）
values	String	是	值。商户公钥加密返回，使用商户私钥解密
type	String	是	类型。 third_3ds_otp：3ds验证码； auth_url：交易授权响应url；
description	String	否	描述
transactionTime	Long	是	交易时间。毫秒时间戳
expirationTime	Long	否	过期时间。毫秒时间戳

通知示例

3ds验证码

{
    "cardNo": "1242352328671924231",
    "tradeNo": "trans1232435363435463432",
    "originTradeNo": null,
    "currency": "CNY",
    "amount": "16.96",
    "merchantName": "ULTRA MOBILE",
    "values": "ajfon34nNOIN24nafaiw4onnfn0iw32ngfn0IF0Q34NFQFOFAW", //明文示例：208346
    "type": "third_3ds_otp",
    "description": null,
    "transactionTime": 1729422898000
}

交易授权响应url

{
    "cardNo": "1242352328671924231",
    "tradeNo": "trans1232435363435463432",
    "originTradeNo": null,
    "currency": "CNY",
    "amount": "16.96",
    "merchantName": "ULTRA MOBILE",
    "values": "ajfon34nNOIN24nafaiw4onnfn0iw32ngfn0IF0Q34NFQFOFAW", //明文示例:https://www.google.com
    "type": "auth_url",
    "description": null,
    "transactionTime": 1729422898000,
    "expirationTime": 1729422899000
}

响应

当返回结构体为下方所示时，回调通知成功

200

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": null
}

持卡人通知

X-WSB-CATEGORY=card_holder

通知参数

参数	类型	是否必传	备注
holderId	Long	是	持卡人ID
merchantOrderNo	String	否	商户订单号
cardTypeId	Long	是	卡片类型ID
email	String	是	邮箱
firstName	String	是	名
lastName	String	是	姓
status	String	是	under_review: 审核中 pass_audit: 审核通过 reject: 拒绝
respMsg	String	是	备注

通知示例

{
    "holderId": 123456,
    "merchantOrderNo": "35nigjaongaognaeorig",
    "cardTypeId": 111016,
    "email": "[e-mail]",
    "firstName": "first",
    "lastName": "last",
    "status": "reject",
    "respMsg": "邮箱错误"
}

响应

当返回结构体为下方所示时，回调通知成功

200

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": null
}