WooCommerce 支付渠道接入全指南（支付宝/微信 + Stripe/PayPal）

引言：买家把商品加进购物车了，卡在最后一步

做外贸站的读者大概率遇到过这种局面：欧美客户下单一切顺利，一个国内客户进站下单，付款方式里只有信用卡，客户直接关掉页面。反过来亦然——装了某款号称「支持国内支付」的插件，海外客户嫌多了一步跳转也流失。更麻烦的是后台：两三种网关同时开着，订单状态一会儿「Pending payment」，一会儿「On hold」，财务对账时对不上，用户已经付过钱但订单没发货，客服只能人工补单。根结通常不在插件本身，而在于你没有把「支付方式 → 回调 → 订单状态 → 币种与税务」这条链路当成一个整体来设计。

原理分析：WooCommerce 的网关到底是什么

WooCommerce 里每一个付款渠道都是一个继承自 WC_Payment_Gateway 的 PHP 类：process_payment() 负责把订单信息抛给第三方并返回跳转地址或处理结果，woocommerce_payment_gateways 过滤器负责把类注册进后台的支付方式列表，webhook/回调地址则由 WC()->api_request_url( 'your_gateway' ) 生成。理解了这三点，你会发现插件只是帮你实现了这些接口，自己改并不神秘。

注意「谁生成二维码」这件事：支付宝/微信的 Native 支付通常由商户服务端调用统一下单接口拿到 code_url，再由前端渲染二维码；而 alipay.trade.page.pay 是对 PC 端直接构造表单跳转。两者验签方式完全不同，混用会拿到 invalid-signature 之类的验签失败响应（微信 V3 常见报错为 SIGN_ERROR / 平台证书不符）。

保姆级实操

步骤 1：先把结算币种与税务口径定下来。 在 WooCommerce → 设置 → 常规里确定货币；如果你同时要收美元和人民币，不要用两套币种并存，而是「单币种 + 前端汇率展示」，否则跨境结算时对账会失控。WooCommerce 多币种与结算配置

步骤 2：安装海外网关。 官方免费插件 WooCommerce Stripe Gateway（WordPress.org 目录名 woocommerce-gateway-stripe）与 WooCommerce PayPal Payments 覆盖了绝大多数海外场景。装好后优先开启 Webhook 自动配置，让插件自己注册回调端点，避免手动填错 URL。Stripe 后台的 STRIPE_API_KEY 请用测试模式先跑通。

步骤 3：国内渠道先确认主体资质。 支付宝当面付、微信支付都要求企业主体 + 已备案域名，个人开发者拿不到商户号。别指望某个插件能绕过这一步。

步骤 4：注册自定义网关骨架。 以下是一个最小可运行的收款网关骨架，真实存在于 WooCommerce 的 WC_Payment_Gateway 体系：

// 放在主题 functions.php 或独立小插件里
add_filter( 'woocommerce_payment_gateways', function ( $gateways ) {
    $gateways[] = 'WC_Gateway_Custom_Alipay';
    return $gateways;
} );

add_action( 'plugins_loaded', function () {
    class WC_Gateway_Custom_Alipay extends WC_Payment_Gateway {
        public function __construct() {
            $this->id                 = 'custom_alipay';
            $this->method_title       = '支付宝（自定义网关）';
            $this->has_fields         = false;
            $this->method_description = '通过 alipay.trade.page.pay 完成 PC 端跳转支付';
            $this->init_form_fields();
            $this->init_settings();
            $this->title       = $this->get_option( 'title' );
            $this->description = $this->get_option( 'description' );
            add_action( 'woocommerce_api_' . strtolower( get_class( $this ) ), [ $this, 'handle_notify' ] );
        }

        public function init_form_fields() {
            $this->form_fields = [
                'enabled'     => [ 'title' => '启用', 'type' => 'checkbox', 'label' => '启用该支付方式', 'default' => 'no' ],
                'title'       => [ 'title' => '前台名称', 'type' => 'text', 'default' => '支付宝' ],
                'description' => [ 'title' => '说明文案', 'type' => 'textarea' ],
            ];
        }

        public function process_payment( $order_id ) {
            $order = wc_get_order( $order_id );
            $order->update_status( 'pending', '等待买家在支付宝完成付款' );
            return [
                'result'   => 'success',
                'redirect' => add_query_arg( [
                    'pay_for_order' => true,
                    'key'           => $order->get_order_key(),
                    'gateway'       => $this->id,
                ], wc_get_checkout_url() ),
            ];
        }

        public function handle_notify() {
            $raw = file_get_contents( 'php://input' );
            // 真实环境必须做 RSA2 验签，验签通过再改订单状态
            if ( isset( $_POST['out_trade_no'] ) && 'TRADE_SUCCESS' === sanitize_text_field( $_POST['trade_status'] ) ) {
                $order = wc_get_order( absint( $_POST['out_trade_no'] ) );
                if ( $order && $order->needs_payment() ) {
                    $order->payment_complete();
                }
            }
            echo 'success'; // 支付宝要求返回明文 success，否则会重复通知
            exit;
        }
    }
} );

步骤 5：把回调地址加白名单。 支付宝/微信要求回调必须是公网 HTTPS 地址且不能被安全插件拦截。若你装了 Wordfence，在防火墙规则里排除 ?wc-api= 这类请求，否则会出现「用户已付款，订单仍在待付款」的经典故障。

步骤 6：跨境收款完成身份与税务信息。 Stripe 会要求填写商业信息并可能触发 KYC；PayPal 大额提现可能需要提供交易凭证。这一步是资金可用性的前提，不是可选项。

常见踩坑

1. 同时启用两家合规级别不同的网关，前端结账页出现重复输入框导致单选失效——用 woocommerce_available_payment_gateways 过滤器按币种或收货国互斥。
2. 案例： 某外贸站把支付宝网关的 notify_url 写成了 http:// 开头，PHP 侧 301 后支付宝收不到 200，重复通知 8 次，导致同一订单被 payment_complete() 多次减库存，最终超卖 3 件。
3. 微信支付 V3 忘记更新平台证书，回调验签失败且后台不报错，表现为长期「Pending payment」。
4. 没有给长任务加超时保护，回调里直接同步调用 Refund 接口导致进程被 Nginx 504 掐断。
5. 用个人主体申请国内支付商户号被驳回，转而使用非官方代收通道，属于资金二清红线，风险极高。
6. 忽略 wc-api 在 CDN 上的缓存，Cloudflare 默认不缓存但配置不当的 Nginx proxy_cache 会缓存回调。
7. 测试模式密钥误上生产，用户付款进了 Sandbox，钱没有了踪影。WooCommerce 订单与邮件通知配置

总结

选网关的判断标准是三条：主体资质是否匹配（决定了能用哪家）、目标客户是否集中在某一地区（决定优先级）、回调能否稳定被三方触达（决定自动化程度）。落地清单：先单币种跑通一个渠道 → 加第二个渠道并做按地区互斥 → 给回调加日志与幂等 → 跨境再补 KYC。支付这块最忌讳一开始就追求「全渠道」，很多残留 bug 其实来自过度并行配置。