优享卡(Card)

本篇文档定义了在优享卡(Card)业务中涉及的核心字典变量,包括交易类型枚举(Transaction Type)以及交易拒绝/状态原因码(Reason Code)。在解析 Webhook 通知或查询交易明细时,请参考下表进行逻辑映射。

1. 卡片交易类型 (Card Transaction Type Enum)

该枚举标识了卡片上发生的资金流转性质。这些值有助于区分正常的消费、冲正/撤销以及内部账户的资金调拨。

枚举值 (Enum Value)描述说明 (Description)
transfer_in资金转入:资金从主账户(Account)划拨进入该优享卡(Card)。
transfer_out资金转出:资金从优享卡(Card)划拨退回至主账户(Account)。
consumption消费扣款:正常的卡片消费/授权交易。
refund退款入账:消费交易完成后的退款(全额或部分退款),资金退回至当前卡片。
settlement_debit清算补扣 (Settlement Debit):例如在 Uber 乘车时预授权了 $10,但最终实际跑完行程的清算金额为 $15,平台将生成一笔金额为 $5 的差额补扣订单。
settlement_refund清算退还 (Settlement Refund):例如预授权了 $10,但最终实际清算金额为 $8,平台将生成一笔金额为 $2 的差额退还订单。
reversal交易撤销 (Reversal):业务逻辑与退款类似,但此类订单通常发生在交易最终清算(Settlement)之前(例如撤销原有的预授权)。
declined_refund失败退回 (Declined Refund):异常场景处理。如果平台成功授权交易并扣除额度,但由于发卡行或其他链路错误导致最终订单失败,平台会主动创建一笔新订单将该笔金额退回。
auth_fee授权费用 (Authorization Fee):在进行交易授权验证时产生的费用。

2. 交易原因码 (Transaction Reason Code Enum)

以下状态码用于标识交易的具体处理结果。特别是在交易被拒绝(Declined)或需要人工介入排查时,开发者可通过提取 Message 字段向终端用户展示友好的提示信息。

原因码 (Code)英文标识 (Message)中文说明 (Description)
100001InsufficientBalance余额不足:账户或卡片内可用余额不足以支付此笔交易。
100002CardNotActive卡状态未激活:当前使用的卡片尚未完成激活操作。
100003MCCNotAllow限制类商户 (MCC):交易涉及系统禁止的商户类别码 (MCC),不予放行。
100004ScenariosRiskControl风控拒绝:该笔交易触发了平台的安全风控规则。
100005SceneBlacklist场景黑名单:该交易场景或收款方已被列入黑名单。
100006SceneWhitelistNoMatch场景未授权:该交易场景不在允许的白名单范围内。
100007SystemDown系统服务异常:内部系统或上游渠道服务出现异常状况。
100008UnknownDeclined未知拒付:交易被拒绝,通常由于收单行未返回具体错误原因。
100009ForceDebit强制扣款:针对此账户/卡片执行的强制性债务扣款。
100010DeleteCardRefund删除卡转出:在卡片被注销或删除后触发的余额清退交易。
100011ShareNotActive共享组不可用:卡片所属的共享资金池或资金组当前处于不可用状态。
100012CustomerAuthRejected客户授权拒绝:客户(或持卡人)拒绝了该项授权请求。
100013SplitTrxSettlement拆分订单清算:该笔交易需要被拆分成多笔进行清算结算。
100014CardRepayment卡负数还款:针对透支或出现负数余额的卡片进行的还款入账。
100015CvvNotMatchCVV 不匹配:交易验证时提供的 CVV(卡片背面的安全码)错误。
100016LimitExceeded超出限额:交易金额超出了卡片设定的单笔或周期消费限额。
100017CardInfoNotMatch卡信息不匹配:提供的卡片信息(如账单地址、持卡人姓名等)与系统记录不符。
100018BankDown银行服务异常:发卡行或清算网络当前服务不可用。
100019BankRiskControl银行风控拒绝:交易被发卡行的风控系统拦截。
200800Approve交易批准:交易已成功获得授权或批准。
200801DoNotHonour不承兑 (Do Not Honour):发卡行拒绝该笔交易,且未提供具体原因。
200802AccountClosed账户已关闭:关联的银行卡账户已被注销或关闭。
200804CardExpired卡已过期:卡片已过有效期,无法进行交易。
200808Restricted受限卡:该卡片被发卡行标记为限制状态(如挂失、冻结等)。
200810FrequencyLimit频率限制:交易过于频繁,触发了防刷单或风控频率限制。
200811InvalidExpiry有效期不匹配:输入的卡片有效期(Exp Date)与发卡行记录不符。