卡

1. 推送事件

事件名	是否重发	描述
CC_CONSUME	是	卡消费
CC_REFUND	是	卡退款
CC_WITHDRAW_CASH	是	卡取现
CC_REDEEM	是	卡赎回
CC_RECHARGE	是	卡充值/抵押（使用API充值卡充值成功后的通知）
3DS_OTP	是	3DS验证码
3DS_CONFIRM	是	3DS确认编码
CR_RECHARGE	是	卡充值申请提交成功通知（仅IFrame场景下使用）
CA_APPLY	是	卡申请提交成功通知
NE_VERIFY	是	验证类通知
KS_KYC	是	KYC通知（提交KYC认证后认证通过或者拒绝时的通知）
CSC_STATUS_CHANGE	是	卡状态通知（卡状态发生变更时的通知，如：使用API激活卡、锁卡、解锁卡等操作的通知）
MF_MATERIAL_FLOW	是	卡寄送物流通知（寄送卡片成功后的通知）
CS_APPROVED	是	开卡成功通知（一张卡只会通知一次） 实体卡：卡状态变更为待激活时触发该通知 虚拟卡：卡状态为正常时触发该通知
CE_EVENT	是	卡事件通知(卡冻结和解冻时触发)
CC_AUTHORIZATION	是	卡交易授权通知(（仅适用于特定共享模式卡段）)

2.全局推送格式

参数名	类型	是否必填项	描述
event	String	是	事件名
trace	String	是	链路ID，同一笔交易的链路ID一样
orderNo	String	是	订单号，全局唯一
timestamp	Long	是	推送时间时间戳(毫秒)
detail	Object	是	推送内容，根据事件不同推送的格式也不一样

2.1. 卡交易推送格式

包含卡消费、卡退款、卡取现、卡赎回、卡充值/抵押

参数名	类型	是否必填项	描述
cardId	String	是	卡唯一ID
cardNumber	String	是	卡号
orderNo	String	是	订单号
customerNo	String	是	客户编号
type	int	是	交易类型(1=充值/抵押,2=消费,3=退款,4=取现,5=赎回,6=管理费)
status	int	是	交易状态(1=成功,2=失败,3=处理中,4=已入账,5=未入账,7=取消)
amount	BigDecimal	是	交易金额
direction	int	是	收支方向(1=收入，2=支出)
merchantName	String	否	商户名
currency	String	是	交易币种
transactionAt	Long	是	交易时间
transactionId	String	是	交易ID,同一笔交易的transactionId一致
originalAmount	BigDecimal	否	原始交易金额
originalCurrency	String	否	原始交易币种
reason	String	否	失败原因
fee	BigDecimal	否	交易手续费
thirdOrderNo	String	否	第三方订单号(卡充值/抵押时有效)
merchantMcc	String	否	MCC
merchantCategory	String	否	商户类别
merchantCountry	String	否	商户国家

2.2. 3DS OTP推送格式

参数名	类型	是否必填项	描述
cardId	String	是	卡唯一ID
cardNumber	String	是	卡号
orderNo	String	是	订单号
customerNo	String	是	客户编号
3dsCode	String	是	3DS验证码
merchants	String	否	商户名
amount	BigDecimal	否	交易金额
transactionCurrency	String	否	交易币种
transactionTime	Long	否	交易时间

2.3. 3DS确认推送格式

参数名	类型	是否必填项	描述
cardId	String	是	卡唯一ID
cardNumber	String	是	卡号
customerNo	String	是	客户编号
type	String	是	3DS确认类型（code / link）
validateCode	String	否	3DS验证码，type=code时有效
url	String	否	3DS确认链接，type=link时有效
merchants	String	是	商户名称
transactionTime	Long	是	交易时间
amount	BigDecimal	是	交易金额
transactionCurrency	String	是	交易币种

2.4. 卡申请提交成功通知推送格式

参数名	类型	是否必填项	描述
cardId	String	是	卡唯一ID
orderNo	String	是	订单号
customerNo	String	是	客户编号
amount	BigDecimal	是	实际支付金额
status	Integer	是	支付状态(1:已支付 2:待支付)
applyAt	Long	是	申请时间

2.5. 充值申请提交成功通知推送格式（仅IFrame场景下使用）

参数名	类型	是否必填项	描述
cardId	String	是	卡唯一ID
orderNo	String	是	订单号
customerNo	String	是	客户编号
cardNumber	String	是	卡号
amount	BigDecimal	是	实际支付金额
status	Integer	是	支付状态(8:待支付)
subscribeAt	Long	是	申请时间

2.6. 验证类通知推送格式

参数名	类型	是否必填项	描述
cardId	String	是	卡唯一ID
orderNo	String	是	订单号
code	String	是	验证码
cardNumber	String	是	卡号
type	String	是	类型(详见2.7验证通知类型)
customerNo	String	是	客户编号

2.7. 验证类通知类型

参数名	描述
CARD_ACTIVATION	卡激活
LOCK_UNLOCK_CARD	卡锁定/解锁
TX_WDR_PWD_MODIFY	修改交易（取现）密码
TX_WDR_PWD_SET	设置交易（取现）密码
CAT_CARD	查看卡片

2.8. KYC通知推送格式

参数名	类型	是否必填项	描述
customerNo	String	是	客户编号
documentType	String	是	证件类型(1:身份证2:护照3:活体,4:驾驶证,5:居留证)
status	String	是	状态(1:已通过 2:已拒绝 3:认证中 4:未认证) 只推送1，2
reason	String	否	认证拒绝原因(仅状态为已拒绝时有效)

2.9. 卡状态通知推送格式

参数名	类型	是否必填项	描述
cardId	String	是	卡唯一ID
cardNumber	String	是	卡号
status	String	是	状态 (1=正常,2=待激活,3=已冻结,4=已锁卡,5=已注销,6=申请中,7=激活中,8=锁卡中,9=解锁中,10=注销中,13=已拒绝,14=已取消,15=换卡中,16=已换卡) 只推送1,2,3,4,5,13
orderNo	String	是	订单号
customerNo	String	是	客户编号
reason	String	否	原因

2.10. 卡寄送物流通知推送格式

参数名	类型	是否必填项	描述
dispatchTime	String	是	发货时间
logisticsOrderNo	String	是	物流单号
logisticsCompanyName	String	是	物流公司名
recipientAddress	String	是	收件地址
logisticsImage	String	是	物流照片
cardId	String	是	卡唯一ID

2.11. 开卡成功通知推送格式

参数名	类型	是否必填项	描述
orderNo	String	是	订单号
cardId	String	是	卡唯一ID
cardNumber	String	是	卡号
customerNo	String	是	客户编号
cardStatus	Integer	是	卡状态(1=正常,2=待激活) 实体卡：卡状态为待激活 虚拟卡：卡状态为正常

2.12 卡事件推送格式

参数名	类型	是否必填项	描述
cardId	String	是	卡唯一ID
event	String	是	事件类型(Frozen=已冻结,Unfrozen=已解冻)
reason	String	否	原因

2.13 卡交易授权通知（仅适用于特定共享模式卡段）

参数名	类型	是否必填项	描述
cardId	String	是	卡唯一ID
cardNumber	String	是	卡号
amount	String	是	交易金额
currency	String	是	交易币种
transactionId	String	是	交易ID
merchantMcc	String	否	MCC
authorizationId	String	是	授权ID
transactionChannel	String	否	交易渠道

备注：当交易发生后，UPay 在完成前置风控及限制校验后，将通过 Webhook 向商户系统推送授权请求。商户需进行决策，并返回通过(approve)或者拒绝(decline)。若商户未在 2.5 秒内响应，该交易将因超时被拒绝。

对于授权接口，HTTP 响应状态码应返回 200，返回值为字符串类型：approve / decline.

代码示例

Java

public ResponseEntity<String> simulation(@RequestBody String body) {
	//return ResponseEntity.status(status).body("decline");
   return ResponseEntity.status(status).body("approve");
}

Go

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

func simulation(c *gin.Context) {
    // 读取请求体
    body, err := c.GetRawData()
    if err != nil {
        c.String(http.StatusBadRequest, "failed to read body")
        return
    }
    
    // 如果需要用 body 做后续处理，可以在这里使用
    _ = string(body) // body 是 []byte，可以转为 string 使用
    
    // 返回 "approve"
    c.String(http.StatusOK, "approve")
}

Python

from flask import Flask, request, make_response

app = Flask(__name__)

@app.route('/simulation', methods=['POST'])
def simulation():
    # 读取请求体
    body = request.get_data(as_text=True)
    
    # 如果需要用 body 做后续处理，可以在这里使用
    # body 是字符串类型
    
    # 返回 "approve"
    return make_response("approve", 200)