核心概念
金额均为整数
Ion 中所有金额均为该货币最小单位的整数——美元用分,日元没有辅助单位,¥500 即为 500,而非
50000。amount: 4200、currency: "usd" 表示 $42.00。
收款(Charge)
收款是从客户处扣款的一次尝试。创建是同步的,结算是异步的——succeeded 表示扣款已获授权,
不代表资金已完成结算。
客户与支付方式
客户是可复用的记录,可关联一个或多个支付方式(卡、银行账户)。预先创建客户而非每次传递原始卡 信息,是实现记忆卡结账和订阅的前提。
幂等键
所有写接口(charges、refunds、subscriptions)均支持 idempotency_key。请求超时后使用相同的键
重试,Ion 会返回原始结果而非创建重复收款;若使用相同键但请求体不同,则视为错误(见
错误)。幂等键应绑定业务动作(如你自己的订单号),而非随机生成。
订阅
订阅将客户与套餐绑定并按周期扣款。订阅有 current_period_end;到期扣款失败时会转为 past_due
而非立即取消,给你留出催收窗口期。
退款
退款关联某笔收款,可部分退款。只要累计退款金额不超过原始金额,可对同一笔收款多次部分退款。