Bigcommerce Process Payment with api 返回 401 错误

2026-10-24支付阿杰

结论

401 Unauthorized 和错误代码 10001 通常与请求体无关，而是 Payments API 没有正确识别 Payment Access Token。最常见的原因是 Authorization header 格式不对。它必须包含 PAT 前缀，不能只传 token，也不能使用 Bearer。

正确格式：

Authorization: PAT {payment_access_token}

还要确认 token 是为当前订单生成的，并且请求中的 order_id 与生成 token 时使用的订单一致。

正确的请求方式

处理付款时，需要调用 Payments API 域名：

POST https://payments.bigcommerce.com/api/public/v1/orders/{order_id}/payments

请求头示例：

Authorization: PAT eyJhbGciOi...
Accept: application/vnd.bc.v1+json
Content-Type: application/json

以下两种写法都可能返回 401：

Authorization: eyJhbGciOi...

Authorization: Bearer eyJhbGciOi...

应写成：

Authorization: PAT eyJhbGciOi...

Payment Access Token 的生成与使用

Payment Access Token 需要通过 BigCommerce REST API 为指定订单创建。创建 token 时使用商店 API 凭证，例如 X-Auth-Token。处理付款时，则使用生成的 Payment Access Token。

这两类 token 不能混用：

创建 Payment Access Token：使用商店的 X-Auth-Token
调用 Process Payment：使用 Authorization: PAT ...

如果创建 token 后得到以下响应：

{
  "data": {
    "id": "eyJhbGciOi..."
  }
}

需要把 data.id 的值放入 Authorization header，而不是传入整个响应对象。

完整的 curl 示例：

curl --request POST \
  --url "https://payments.bigcommerce.com/api/public/v1/orders/123/payments" \
  --header "Authorization: PAT eyJhbGciOi..." \
  --header "Accept: application/vnd.bc.v1+json" \
  --header "Content-Type: application/json" \
  --data '{
    "payment": {
      "instrument": {
        "type": "card",
        "number": "4111111111111111",
        "cardholder_name": "BP",
        "expiry_month": 12,
        "expiry_year": 2030,
        "verification_value": "411"
      },
      "payment_method_id": "authorizenet.card",
      "amount": 81,
      "currency_code": "USD"
    }
  }'

其中的 order_id、金额、币种、支付方式和测试卡信息，都需要替换为当前商店和支付网关实际支持的值。

仍然返回 401 时的检查顺序

1. 检查 `PAT` 前缀

确认最终发出的 header 是：

Authorization: PAT <token>

同时检查客户端、代理或服务器是否删除了 Authorization header。排查时应查看实际发送的 HTTP 请求，不能只看代码中的配置。

2. 检查订单是否匹配

Payment Access Token 与创建它时指定的订单相关。如果 token 是为订单 123 创建的，请求地址也必须使用订单 123：

https://payments.bigcommerce.com/api/public/v1/orders/123/payments

同一个 token 如果用于其他订单，可能会被拒绝。

3. 重新生成 token

不要长期保存并反复使用旧的 Payment Access Token。如果不确定 token 是否过期、是否已经使用过，或者复制时是否遗漏了内容，应为当前订单重新生成 token，并立即调用支付接口。

复制 token 时还要注意：

不要带上多余的引号
不要包含换行或空格
不要只复制 token 的一部分
不要把商店 API access token 当作 Payment Access Token

4. 检查请求域名

Payment Access Token 应发送给 Payments API：

https://payments.bigcommerce.com/api/public/v1/...

不要把 Process Payment 请求发到商店管理 API 地址，例如：

https://api.bigcommerce.com/stores/{store_hash}/...

有些 HTTP 客户端会同时应用全局认证和请求级认证，结果可能产生两个 Authorization header，或者由后设置的 Bearer token 覆盖 PAT token。最终请求中应只有一个有效的认证 header。

请求体中还存在的问题

解决 401 后，示例请求体仍可能因支付方式或参数校验失败而报错。

`cod` 通常不是可在线处理的支付方式

cod 表示货到付款一类的离线支付方式。Process Payment API 主要用于通过已配置的支付网关处理付款，不能默认认为 cod 可以通过该接口完成扣款。

应使用当前订单实际可用并支持 API 处理的 payment_method_id，不要只根据支付方式名称手写这个值。

卡支付请求需要完整字段

第二个示例缺少 amount 和 currency_code。建议提交完整的付款信息：

{
  "payment": {
    "instrument": {
      "type": "card",
      "number": "4111111111111111",
      "cardholder_name": "BP",
      "expiry_month": 12,
      "expiry_year": 2030,
      "verification_value": "411"
    },
    "payment_method_id": "authorizenet.card",
    "amount": 81,
    "currency_code": "USD"
  }
}

示例中的 expiry_year: 2020 已经过期，当前测试不能再使用。测试卡号、CVV 和有效期也必须符合所配置支付网关的测试环境要求。

支付网关和币种必须匹配

只有商店已经正确配置相应网关，并且当前订单可以使用该支付方式时，authorizenet.card 才有效。PKR 也必须同时受到商店、订单和支付网关支持。

认证成功后，这些问题通常表现为 400、422 或支付网关拒绝，而不是 401。因此，应先解决 Authorization header 和 token，再检查请求体参数及支付网关配置。