如何在 WooCommerce Stripe 支付中正确添加订单税务元数据

本文详解如何通过 wc_stripe_payment_metadata 钩子向 Stripe 支付请求注入准确的订单税务与费用元数据（如折扣、运费、税费等），解决因方法过时或键名冲突导致元数据未显示的问题。

在 WooCommerce 中集成 Stripe 时，很多开发者都会遇到一个典型问题：订单的税务与费用明细没能正确同步到 Stripe 后台。这听起来像是个小问题，但实际排查起来，往往牵扯到钩子参数、数据访问方式和键命名规范等多个细节。即便正确挂载了 wc_stripe_payment_metadata 过滤器，自定义元数据也可能在 Stripe Dashboard 的 Payment 或 Charge 对象中杳无踪影。问题的根源，通常集中在三个方面：钩子参数误用、过时的数据访问方式，或元数据键名不符合 Stripe 规范。

正确实现方式

正确做法其实并不复杂，但有几个关键点必须注意。首先，确保使用 WooCommerce 4.0+ 推荐的订单方法——而不是已弃用的 $order->get_data() 数组直接访问。原因在于，Stripe 插件内部依赖这些方法的返回值进行类型校验与序列化，旧方法会引发兼容性问题。

add_filter('wc_stripe_payment_metadata', 'add_tax_and_fee_metadata_to_stripe', 10, 3);
function add_tax_and_fee_metadata_to_stripe($metadata, $order, $prepared_payment_method) {
    // 使用现代 WC_Order 方法获取数值（自动处理格式化与精度）
    $metadata['order_discount_total']     = (string) $order->get_discount_total();
    $metadata['order_discount_tax']       = (string) $order->get_discount_tax();
    $metadata['order_shipping_total']     = (string) $order->get_shipping_total();
    $metadata['order_shipping_tax']       = (string) $order->get_shipping_tax();
    $metadata['order_cart_tax']           = (string) $order->get_cart_tax();      // 即商品行项目税额总和
    $metadata['order_total_tax']          = (string) $order->get_total_tax();     // 订单总税额（含运费税等）
    // 可选：添加业务标识字段（避免空格/特殊字符，推荐下划线命名）
    $metadata['order_id']                 = (string) $order->get_id();
    $metadata['billing_company']          = $order->get_billing_company() ?: 'N/A';
    return $metadata;
}

这里有几个关键修正点值得专门提一下：

• 参数第三项是 $prepared_payment_method，不是 $source：旧版文档或示例中可能沿用过时签名，但当前 Stripe 官方插件（v7.0+）明确要求第三个参数为支付方式对象。如果签名不对，钩子会被跳过或静默失效，这是最常见的隐性错误。
• 避免使用 __() 翻译函数作为 metadata 键名：Stripe 元数据键（key）必须是 ASCII 字符串，且不支持空格、中文或翻译上下文。原代码中类似 'Discount Total' 这样的写法，会因空格和本地化导致键名非法，Stripe 会直接丢弃该条目。正确做法是改用 snake_case 格式，如 order_discount_total。
• 强制类型转换为字符串：Stripe API 要求所有 metadata 值为字符串。浮点数（如 29.99）若未转为字符串，可能被截断或解析异常；使用 (string) 显式转换，可以确保精度与兼容性。
• 优先使用 get_*() 方法：相比 $order->get_data() 数组直接访问，$order->get_discount_tax() 等方法内置了四舍五入控制、货币精度适配及空值安全处理，更可靠。

验证与调试建议

如果元数据依然没显示出来，可以按下面几步来排查：

1. 启用 Stripe 日志：在 WooCommerce → 设置 → 结账 → Stripe → 高级设置 中开启「启用日志」，然后检查 wp-content/uploads/wc-logs/stripe-* 日志文件，确认你的钩子是否被调用（搜索 wc_stripe_payment_metadata）。
2. 检查 Stripe Dashboard：成功提交后，在 Stripe Dashboard → Payments 中点击对应 Payment → 查看右侧 Metadata 区域（注意不是 Charges 标签页），确认字段是否存在。
3. 避免重复键冲突：Stripe 元数据键名全局唯一，如果插件或其它代码已写入同名键（如 order_id），后写入者会覆盖前者。建议添加前缀（如 wc_）来提升健壮性：'wc_order_total_tax' 这类命名更稳妥。

总结

向 Stripe 注入 WooCommerce 订单元数据，不是简单赋值就能搞定的事。它需要兼顾 钩子签名准确性、键名合规性、值类型安全性及 WooCommerce 版本兼容性。使用标准化的 get_*() 方法、纯 ASCII 下划线键名、显式字符串转换，并通过日志验证执行路径，才能稳定、可维护地将关键税务与费用信息同步至 Stripe，为后续的财务自动化打下坚实基础。