WooCommerce自定义支付插件调用网关API遇403权限拒绝错误求助

问题背景 #

我正在开发一款WooCommerce自定义支付方式插件，通过RESTful接口将客户重定向至支付网关，集成时需使用网关提供的API密钥（Token）。根据文档要求，需向API端点https://api.example.com/api/v1/payment-terminal/发送POST请求，请求体的username字段传入客户手机号（文本类型）。

成功响应示例：

{
  "status": 200,
  "error": "",
  "message": "",
  "data": {
    "cash_wallt": 0,
    "special_amount": 0
  },
  "patch": [],
  "date": "2024-10-16 12:57:47"
}

插件核心处理函数：

public function process_payment($order_id) {
    $order = wc_get_order($order_id);
    $amount = $order->get_total();
    $description = sprintf(__('Order #%s', 'woocommerce'), $order->get_order_number());
    $customer_phone = $order->get_billing_phone();

    // Step 1: Check Customer Credit
    $credit_response = wp_remote_post('https://api.example.com/api/v1/payment-terminal/', [
        'headers' => [
            'Authorization' => 'Bearer ' . $this->apikey, // API key
            'Content-Type'  => 'application/json'
        ],
        'body' => json_encode(['username' => $customer_phone]) // Customer phone number
    ]);

    if (is_wp_error($credit_response)) {
        wc_add_notice('Authentication error', 'error');  
        return;
    }

    $credit_body = json_decode(wp_remote_retrieve_body($credit_response), true);
    if ($credit_body['status'] != 200) {
        wc_add_notice('Failed Authentication', 'error'); 
        return;
    }
    
}

当前问题：选择该网关结账时持续返回403 Forbidden错误。已核实以下内容：

• API密钥（Token）正确且已包含在请求头中
• 客户手机号与网关注册账号一致
• 服务器IP已加入网关白名单

为排除插件代码问题，使用curl直接发送请求：

curl -X POST https://api.example.com/api/v1/payment-terminal/ \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d "{\"username\": \"{phone number}\"}"

curl响应结果：

{
  "status": 403,
  "error": null,
  "message": "permission denied",
  "data": [],
  "patch": [],
  "date": "2024-12-09 20:13:21"
}

网关文档内容 #

简介：本文档所有Web服务均为RESTful架构。

认证：需在请求头中使用apikey令牌，令牌需向我方工作人员获取，申请时需提供网站回调URL，所有请求为POST类型。

查询平台余额：向该端点请求可获取用户现金钱包及专项信用余额，支付仅通过平台钱包处理。

必填字段：username（用户手机号，文本类型），请求路径：api.[gateway].com/api/v1/payment-terminal/

成功响应将展示cash_wallt（现金钱包余额）及special_amount（专项信用余额）。

排查思路 #

• 核对认证头格式：文档提到"使用apikey令牌"，但代码和curl中用了Bearer {token}格式，确认网关是否要求Authorization: Apikey {token}而非Bearer模式——部分网关会对认证头的前缀有严格要求。
• 回调URL校验：文档明确申请令牌时需提供网站回调URL，检查以下两点：
  • 申请时提交的回调URL是否与当前站点的回调URL完全一致（包括HTTP/HTTPS、域名、路径，无多余后缀）
  • 网关是否要求回调URL必须能正常访问（返回200状态），可直接在浏览器或curl中测试回调URL的可用性
• 请求参数细节：
  • 确认手机号格式是否完全匹配网关注册时的格式（如是否带区号、空格、特殊符号，网关是否要求纯数字格式）
  • 检查请求体的JSON格式是否严格符合要求，比如是否存在多余的转义字符（curl中的转义是否正确，代码中json_encode是否生成标准JSON）
• 令牌权限范围：联系网关工作人员，确认当前令牌是否具有payment-terminal端点的访问权限——部分令牌会被限制仅能访问特定接口，或仅支持测试环境/生产环境某一端点
• 环境差异检查：如果测试环境和生产环境使用不同令牌，确认当前使用的令牌是否对应请求的环境（比如测试令牌调用了生产端点）
• 请求头完整性：检查是否有遗漏的必填请求头，比如是否需要添加User-Agent、Accept等通用头，部分网关会校验这些字段
• IP白名单精度：确认服务器的公网IP是否完全正确，部分服务器使用NAT或代理，实际请求的出口IP可能与预期不符——可通过curl https://api.ipify.org获取实际出口IP后再次核对白名单

内容的提问来源于stack exchange，提问作者Vanda Nojan - وندا نوژن