卡交易通知、查询、费用与退款的接入口径,避免漏单和重复扣款。
卡交易、手续费与退款
消费、结算、撤销、退款和费用变化共用 card.transaction.updated。没有单独的 card.transaction.refunded 事件。按 event_type 接收通知,再按data.kind、data.status 和 data.direction 区分业务。
收到通知后回查
- 验签并按
event_id去重,保存通知后返回成功。 - 用
data.card_id和data.id查询:GET /v1/cards/{id}/transactions?id=ctx_...,并传该会员的x-on-behalf-of。 - 按
ctx_ID 更新现有记录,不能每收到一次通知就再插一笔消费或再扣一次钱。查询结果是当前快照,旧通知晚到时仍应回查当前值。 - 通知失败可重试,同一交易的结算和费用变化会再次通知。定期回查完整分页补漏;
from/to筛选的是交易发生时间,不能拿“上次同步时间”筛选旧交易的费用更新。
通知与查询共用 kind、status、direction、posted、settlement_status、updated_at、费用及原币/账单字段。通知携带 card_id;查询还提供展示金额和商户信息。original_transaction_id 在能关联到本卡、本商户的原交易时给出 ctx_ ID;缺失不代表退款无效,也不能自行用金额相同的记录猜关联。
交易类型 kind
以下是当前标准类型全集。类型是开放枚举,新增值须保留和回查,不能丢弃。资金方向以 direction 为准,不按类型名硬编码;同一种服务费也可能有返还方向。
| 值 | 含义 |
|---|---|
auth | 消费授权/消费记录 |
corrective_auth | 消费调整 |
verification | 验卡授权,金额可能为零 |
void | 消费撤销或授权释放 |
refund | 商户退款,可为部分退款,可无原交易关联 |
corrective_refund | 退款调整 |
corrective_refund_void | 退款调整撤销 |
refund_reversal | 退款撤回 |
recharge | 转入到卡 |
recharge_return | 卡内余额退回 |
discard_recharge_return | 销卡余额退回 |
service_fee | 独立服务费记录 |
fund_in | 资金转入 |
atm_inquiry | ATM 查询 |
atm_withdrawals | ATM 取现 |
atm_inquiry_failed_return | ATM 查询费退回 |
atm_withdrawals_failed_return | ATM 取现退回 |
auth_failed_return | 消费失败退回 |
部分产品保留扩展类型,例如 purchase、authorization、reversal、authorization_reversal 或产品交易码。仍以返回的方向及入账事实判断,未知类型进入待核对队列,不把它默认当消费或收入。
状态与方向
status | 含义与处理 |
|---|---|
pending / processing | 处理中,继续回查 |
authorized | 已授权、尚未完成结算;可能占用可用额度 |
succeed | 交易处理成功;仍需区分本金、资金搬运与费用 |
failed | 交易失败;费用仍可能单独发生或返还 |
void | 原交易已撤销;释放授权占用,不把原来未扣的本金再次退款 |
状态同样是开放枚举。未知状态不能自动当成功或失败。
direction 是封闭枚举:debit 支出、credit 收入、none 无本金方向、unknown 方向尚未确认。amount 始终为非负整数串,不能按正负号判断收支。
posted=true 表示这条交易的本金已在 zinfra 卡账本过账;false 不等于失败,授权、零元验卡、未过账授权的撤销以及由独立业务单入账的充值/转出都可能为 false。不能用它推断手续费是否已收,费用看费用字段。
settlement_status 为当前结算标记,常见 Unsettled、Settled、空串或 N/A。独立服务费及资金搬运可以没有结算标记。不要把空串统一显示成“未结算”。
金额和费用
所有 amount、bill_amount 及费用金额都是最小单位整数串;例如 USD、scale=6的 "100000" 是 0.10 USD。原币金额 original_amount 是十进制原文,不能套用该精度。
| 字段 | 口径 |
|---|---|
amount | 卡本币展示额,优先已存卡内变动,否则授权占用;不是每次更新的增量 |
bill_amount | 已知卡本币账单额,优先结算额;未知时可能省略,不现场换汇 |
bank_fee | 当前累计已知银行手续费,不是本次新增扣款 |
bank_fee_return | 本条记录累计已知银行手续费返还;可能随撤销/退款记录给出 |
zinfra_fee | 当前 zinfra 手续费金额,按实际返回值处理,不假定永远为零 |
fee_paid | 消费费用流程当前已收净额,退费后可能降低;不是累计历史收费总额 |
fee_due | 消费费用流程当前未结清额 |
fee_state | none 无费用流程、reserved 授权阶段、processing 处理中、due 待收、refunding 退费中、settled 已结清、review 待核对 |
fee_currency / fee_scale | 费用币种/精度 |
bank_fee 与 bank_fee_return 是费用证据,fee_paid / fee_due 是费用流程状态,不是可以相加的四笔收费。也不能把 bank_fee、zinfra_fee 再加到可能已含费的amount 上。查询卡片余额获取当前可用额,不用流水展示额相加替代余额。
退款、撤销与费用返还
- 商户退款:通常为单独的
refund交易、direction=credit。按该退款的ctx_ID去重,不能把原消费删掉;多笔部分退款分别保留。 - 授权撤销:授权尚未过账时是释放占用,不能再给用户加一笔未曾扣除的本金。通过原交易状态和卡余额回查确认。
- 手续费返还:读取
bank_fee_return,以及原交易后续的fee_paid、fee_due、fee_state。费用返还与本金退款不保证相同时间或相同金额。 - 独立服务费:保留
service_fee流水及其方向。不能因为不是auth就忽略,也不能同时把独立费用记录和费用快照重复扣两次。 - 充值/转出/销卡退回:与对应充值单、转出单核对,只入账一次,不能又按消费退款再记一次。
接入方应以 zinfra 回查数据修正自己的流水投影。若自行向用户加收零售费用,单独保存商户自身的费用记录,不改写 zinfra 原始交易快照。