集成Stripe支付或Stripe Connect时应用需存储哪些Stripe::Charge字段?
Stripe Charge 数据本地存储的字段选择最佳实践
存储核心原则很简单:只存日常业务查询、对账、客服排查需要高频用到的字段,既不要全量冗余存储,也不要只存最基础的两个字段,导致每次查状态都要调用Stripe接口拉数据。
所有场景都必须留存的核心字段
不管是普通单商户支付,还是多商户分账的Stripe Connect场景,这些字段是所有业务都绕不开的:
- Charge的全局唯一ID(对应返回值里的
id,格式为ch_xxx):用来后续和Stripe侧做全链路对账、快速定位对应支付记录 - 支付状态(对应
status字段):存储succeeded、failed、pending这类枚举值,让应用可以快速判断订单支付进度,不需要每次拉取接口数据 - 本地业务关联主键:你自己系统内的订单ID、对应用户ID,用来把Stripe的支付记录和本地业务数据做绑定,这部分虽然不是Stripe返回的字段,但是关联关系必须落库
- 实扣金额与币种:对应
amount(注意Stripe返回的是货币最小单位,比如美元存储的是分数值,不要直接当成整数金额存)、currency,用来和本地订单的应收金额做校验,防止前端传值被篡改 - Stripe侧支付创建时间戳(对应
created字段):用来做对账时的时间基准,不要拿本地收到webhook回调的时间当实际支付完成时间
使用Stripe Connect分账场景需要额外补存的字段
如果你是做多商户平台,走Stripe Connect的分账逻辑,还需要把这些和结算相关的字段落库:
- 分账目标商户账户ID:对应
destination字段的acct_xxx值,对账时可以快速定位这笔钱最终要打给哪个入驻商户 - 平台抽成金额:对应
application_fee_amount字段,是平台从这笔交易里抽取的服务费,生成平台结算报表的时候不需要再逐笔调Stripe接口统计 - 转账链路关联标识:对应
transfer或transfer_group字段,可以串起“用户付款→平台扣费→商户到账”的全资金链路,排查打款异常的时候不用翻多层记录
按需选择存储的字段
这些字段不是必须存,看你自己的业务需求判断要不要加:
- 支付失败原因:如果
failure_code和failure_message不为空就存下来,客服排查用户支付失败问题、处理用户投诉的时候可以直接查,不用翻Stripe的后台日志 - 退款状态与已退金额:对应
refunded布尔值、amount_refunded数值,处理售后退款的时候可以快速判断这笔订单有没有退过、累计退了多少 - 支付收据链接:对应
receipt_url,如果你的系统没有配置自动发送Stripe官方收据,把链接存下来,用户索要支付凭证的时候可以直接提供 - 卡支付核心摘要信息:从
payment_method_details里提取卡组织、卡尾号这类摘要字段,用户在个人中心查支付记录的时候可以直观显示“尾号4242的Visa卡支付”,不需要额外调接口拉取 - 支付争议标记:对应
disputed布尔值,一旦标记为真可以第一时间提醒运营介入处理用户的银行拒付申请
完全没必要存储的字段
这些字段存了属于纯冗余,还容易出现本地数据和Stripe侧数据不一致的问题:
- 所有可以通过Charge ID随时从Stripe拉取的非高频字段,比如完整的账单地址、卡全量校验结果、风险评估的全量详情,需要的时候实时调接口拿就行
- 大体积的嵌套结构数据,比如退款列表的全量详情、支付结果的全量
outcome对象,存在本地既占空间,后续如果Stripe侧数据更新了,本地存的快照反而会误导业务判断
最后提醒一个实际开发的常见坑:别图省事把整个Stripe返回的JSON对象全塞数据库的单个JSON字段里,把要存的高频查询字段拆成独立的列,后续做状态筛选、生成交易报表的时候查询效率会高很多。
内容的提问来源于stack exchange,提问作者stevec
相关产品推荐
相关产品推荐

