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

本篇文章向大家介绍《如何在 WooCommerce Stripe 支付中正确添加订单税务元数据 》，主要包括，具有一定的参考价值，需要的朋友可以参考一下。

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

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

在 WooCommerce 中集成 Stripe 时，常需将订单明细（尤其是税务相关字段）以 metadata 形式传递至 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，为后续财务自动化打下坚实基础。

好了，本文到此结束，带大家了解了《如何在 WooCommerce Stripe 支付中正确添加订单税务元数据 》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！