BigCommerce Get Accepted Payment Methods 未返回全部支付方式

2026-10-10支付小周

结论

Get Accepted Payment Methods 返回的不是后台已配置支付方式的完整清单，而是当前订单在现有币种、账单地址、渠道等条件下，能够通过 BigCommerce Payments API 实际处理的支付方式。

如果接口只返回一种方式，通常说明这个订单只有这一种方式符合条件。后续请求应使用返回项中的 id，通常对应 payment_method_id。不要根据 Get All Payment Methods 返回的配置数据自行推导或拼接这个 ID。

正确的调用流程

支付方式需要在订单创建后查询，不能只根据 cart 或 checkout 查询：

创建 cart。
创建或更新 checkout。
补全账单地址、收货地址和配送方式。
将 checkout 转换为 order。
为该 order 创建 Payment Access Token。
使用 Payment Access Token 查询该 order 的 accepted payment methods。
从响应中读取 id，处理付款时将其作为 payment_method_id 提交。

流程如下：

Cart
  → Checkout
  → Complete addresses and shipping option
  → Order
  → Payment Access Token
  → Accepted Payment Methods
  → Process Payment

创建 Payment Access Token

Payment Access Token 应由服务端创建。下面的路径和字段采用 BigCommerce Payments API 的常见调用方式，实际使用时请以当前官方文档为准：

const response = await fetch(
  `https://api.bigcommerce.com/stores/${storeHash}/v3/payments/access_tokens`,
  {
    method: 'POST',
    headers: {
      'X-Auth-Token': bigCommerceAccessToken,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({
      id: String(orderId),
    }),
  }
);

if (!response.ok) {
  throw new Error(`Unable to create payment access token: ${response.status}`);
}

const result = await response.json();
const paymentAccessToken = result.data?.id;

这里的 orderId 必须是已经创建的订单 ID，不能使用 cart_id 或 checkout_id。

查询订单可接受的支付方式

取得 Payment Access Token 后，调用 accepted payment methods 接口：

const response = await fetch(
  `https://payments.bigcommerce.com/api/public/v1/orders/${orderId}/payment-methods`,
  {
    method: 'GET',
    headers: {
      Authorization: `PAT ${paymentAccessToken}`,
      Accept: 'application/vnd.bc.v1+json',
    },
  }
);

if (!response.ok) {
  throw new Error(`Unable to load payment methods: ${response.status}`);
}

const result = await response.json();

const paymentMethods = Array.isArray(result)
  ? result
  : result.data ?? [];

for (const method of paymentMethods) {
  console.log({
    id: method.id,
    name: method.name,
    type: method.type,
  });
}

返回结构可能随 API 版本或支付方式类型而变化，请以实际响应和当前接口文档为准。处理时要读取 accepted payment methods 返回项中的 id：

const selectedMethod = paymentMethods.find(
  method => method.id === selectedPaymentMethodId
);

if (!selectedMethod) {
  throw new Error('Selected payment method is not accepted for this order');
}

const paymentMethodId = selectedMethod.id;

然后在支付请求中使用该 ID：

const paymentPayload = {
  payment: {
    payment_method_id: paymentMethodId,
    instrument: {
      type: 'card',
      number: cardNumber,
      cardholder_name: cardholderName,
      expiry_month: expiryMonth,
      expiry_year: expiryYear,
      verification_value: cvv,
    },
  },
};

不同支付方式对 instrument、跳转流程和附加字段的要求并不相同。银行卡示例不能直接用于 PayPal、钱包或线下支付方式。

为什么后台配置了多个，接口却只返回一个

后台启用某种支付方式，不等于当前订单能通过 Payments API 使用它。常见限制包括：

支付网关不支持当前订单币种。
支付方式受到国家或账单地址限制。
订单尚未设置完整的 billing address。
checkout 尚未选择配送方式，订单状态不完整。
支付方式仅适用于特定 storefront、channel 或站点。
网关仍处于测试状态，或商户账户配置不完整。
某些线下支付、重定向支付或第三方钱包不会通过通用 Payments API 暴露。
某种支付方式只能通过 BigCommerce Hosted Checkout 或对应的 SDK 流程使用。
Payment Access Token 对应的是其他订单，或者已经失效。

排查时，先检查订单中的这些数据：

order currency
billing country
shipping country
shipping option
channel/storefront
order total
payment gateway availability

修改地址、币种或配送信息后，应重新确认订单状态，并再次查询该订单当前可接受的支付方式。

`Get All Payment Methods` 为什么没有可提交的 ID

Get All Payment Methods 返回的内容更接近商店的支付配置或网关清单。它可以用来查看后台启用了哪些支付能力，但不能说明某种方式是否适用于特定订单，也不保证包含 Payments API 所需的 payment_method_id。

不要进行下面这种转换：

// 不可靠：不要根据名称自行生成 payment_method_id
const paymentMethodId = method.name.toLowerCase().replaceAll(' ', '_');

支付方式名称、配置标识和交易接口使用的 ID 可能各不相同。只有订单级 accepted payment methods 响应实际返回的 ID，才能用于该订单的支付请求。

React Native 场景下的安全注意事项

不要在 React Native 应用中直接保存或使用 BigCommerce 的 X-Auth-Token。移动端代码和网络请求都可能被提取。令牌泄露后，攻击者可能获得商店管理权限。

相关操作应由自己的服务端完成：

React Native
  → Your backend
  → BigCommerce Management API / Payments API

服务端负责创建订单和 Payment Access Token，并执行需要商店级凭据的操作。客户端只接收完成当前结账所需的短期数据。

如果后台已配置的某种支付方式始终没有出现在 accepted payment methods 响应中，通常说明它不符合当前订单条件，或者不支持通过这套 Payments API 流程处理。此时不能从其他接口补出一个“支付方式 ID”后强行提交，而要改用该支付方式要求的 Hosted Checkout、跳转支付或专用集成流程。