Stripe自动更新过期卡时用哪个webhook区分网络更新与手动更新

要区分一次卡片更新来自卡网络自动同步还是通过API手动修改,看webhook事件类型即可:payment_method.automatically_updated 对应卡网络发起的自动更新,payment_method.updated 对应通过API调用完成的更新。两类事件都会带上卡片新的有效期和后四位,便于你同步本地记录。这是Stripe在支付方式事件层面的机制区分,不涉及卡片由哪家网络发行。

网络自动更新、automatically_、含新有效期
本文涉及的概念与核对环节。

两个事件各自对应什么操作

payment_method.updated 通知的是:有人通过API调用对这张卡做了更新。资料对该事件的描述限于“通过API调用更新卡”,没有列举具体可变更字段,实际会改动哪些字段需要以你自己的调用和返回结果为准,不要预设它一定包含某一类字段。

payment_method.automatically_updated 通知的是:卡网络对卡片做了自动更新。发卡行在卡片到期换新或换发新卡时,把新信息推送给卡网络,Stripe接收到后以这个事件通知你。资料明确说明,这类事件包含卡片的新有效期和后四位,便于你据此更新自己的记录。

判断逻辑因此很直接:收到 payment_method.automatically_updated,说明是网络侧完成了换卡信息同步;收到 payment_method.updated,说明这次变更由API调用触发。

卡号变化时指纹会变

如果这次更新涉及新的卡号,Stripe侧的指纹(fingerprint)会发生变化。资料只说明这一事实,没有给出更细的匹配规则。因此在实现上,可以把支付方式ID作为关联本地记录的主键,把指纹变化当作一个独立信号处理,而不是用它来否定更新事件的归属。这属于工程实现建议,不是文档规定的规则。

处理上的几个要点

把两个事件的处理器分开写,通常比在一个处理器里用条件分支判断更清晰。automatically_updated 的处理器专注于把新有效期和后四位写回订阅或客户记录;updated 的处理器处理API侧发起的变更,并按你的业务规则决定是否追加校验。幂等处理属于通用工程实践,是否必要取决于你自身的事件投递与重试情况,资料未对此作出说明。

资料明确指出,无法事先识别哪些卡支持自动更新。也就是说,不能在客户绑卡时预判“这张卡以后会不会自动同步”,只能通过监听事件在更新发生时获知。这一限制应写进运维预期,而不要试图用卡BIN或其他字段提前筛选。

适用范围

上述两个事件的语义是Stripe平台层面的机制说明。卡网络自动更新的实际覆盖情况因国家而异,资料明确表示国际支持程度各国不同,且未给出具体国家清单或资格条件。因此在面向多地区用户设计流程时,不要假定自动更新在所有市场都可用;对未收到 automatically_updated 的到期卡,仍应保留常规的换卡提醒和重试策略。

概括来说:用事件类型区分来源,用支付方式ID做关联,把指纹变化作为辅助信号,并且不预设自动更新的地区覆盖。

原始资料

docs.stripe.com

上一篇 Stripe 已保存银行卡的四类可更新字段