Z Zise Developers English
卡发行 › 指南

卡交易通知、查询、费用与退款的接入口径,避免漏单和重复扣款。

卡交易、手续费与退款

消费、结算、撤销、退款和费用变化共用 card.transaction.updated。没有单独的 card.transaction.refunded 事件。按 event_type 接收通知,再按data.kind、data.status 和 data.direction 区分业务。

收到通知后回查

  1. 验签并按 event_id 去重,保存通知后返回成功。
  2. 用 data.card_id 和 data.id 查询:GET /v1/cards/{id}/transactions?id=ctx_...,并传该会员的 x-on-behalf-of。
  3. 按 ctx_ ID 更新现有记录,不能每收到一次通知就再插一笔消费或再扣一次钱。查询结果是当前快照,旧通知晚到时仍应回查当前值。
  4. 通知失败可重试,同一交易的结算和费用变化会再次通知。定期回查完整分页补漏;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_inquiryATM 查询
atm_withdrawalsATM 取现
atm_inquiry_failed_returnATM 查询费退回
atm_withdrawals_failed_returnATM 取现退回
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_statenone 无费用流程、reserved 授权阶段、processing 处理中、due 待收、refunding 退费中、settled 已结清、review 待核对
fee_currency / fee_scale费用币种/精度

bank_fee 与 bank_fee_return 是费用证据,fee_paid / fee_due 是费用流程状态,不是可以相加的四笔收费。也不能把 bank_fee、zinfra_fee 再加到可能已含费的amount 上。查询卡片余额获取当前可用额,不用流水展示额相加替代余额。

退款、撤销与费用返还

接入方应以 zinfra 回查数据修正自己的流水投影。若自行向用户加收零售费用,单独保存商户自身的费用记录,不改写 zinfra 原始交易快照。

相关接口