Stripe Checkout发票添加法定文本：Webhook触发过快致编辑失败

方案1：修改发票自动定稿设置，手动处理草稿发票 #

这是最直接的解决方式，通过让订阅发票先处于草稿状态，获得修改时间窗口：

1. 调整Stripe账单设置
   进入Stripe后台的「设置 > 账单 > 发票」，找到「发票定稿」选项，取消勾选「自动定稿发票」。此后订阅生成的新发票会保持draft（草稿）状态，不会自动定稿。
2. 监听invoice.created Webhook事件
   当触发该事件时，发票处于草稿状态，可直接通过API修改其footer字段。从事件数据中提取以下关键信息：
   • B2B判定：通过invoice.customer_details.tax_ids是否存在有效税号判断（客户选择企业购买并输入税号后，该字段会有值）
   • 地区信息：invoice.customer.address.country或invoice.customer_details.address.country
3. 根据规则生成法定文本并更新发票
   按照你的判定逻辑生成对应文本后，调用Stripe API更新发票：

   curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \
     -u sk_test_your_secret_key: \
     -d footer="生成的法定文本内容"
   

4. 手动定稿发票
   更新完成后，调用API将发票定稿，触发后续支付流程：

   curl https://api.stripe.com/v1/invoices/{INVOICE_ID}/finalize \
     -u sk_test_your_secret_key:
   

方案2：使用Checkout Session元数据传递预计算文本 #

如果不想修改自动定稿设置，可在Checkout流程中提前计算好法定文本，通过元数据传递给发票：

1. 在Checkout完成后计算并存储文本
   监听checkout.session.completed事件，从事件数据中提取客户的企业身份标识、税号和地区信息，按照规则生成法定文本，将其存入客户对象的metadata或Checkout Session的metadata中。
2. 利用发票模板动态填充
   在Stripe后台的发票模板设置中，启用动态元数据变量，将模板的footer设置为{{metadata.exemption_text}}。当发票创建时，会自动读取对应元数据字段的值，填充到footer位置。

注意事项 #

• 确保Webhook事件处理的幂等性：同一事件可能重复触发，需通过事件ID或idempotency_key避免重复操作。
• 税号有效性验证：Stripe会自动验证欧盟税号的有效性，可通过tax_ids[0].valid字段确认税号是否有效，以此准确判定B2B交易。

内容的提问来源于stack exchange，提问作者Orcun