Bigcommerce Checkout Order API 创建订单失败

2026-10-24支付小周

结论

整体顺序基本正确，但有两点需要调整：

Checkout Order API 只能将完整且可提交的 checkout 转换为 order。仅创建 cart、添加 billing address 和 consignments 并不足够。对于需要配送的 consignment，至少要选择有效的 shippingOptionId，同时补齐访客邮箱等必填信息。
Create Transaction 不是信用卡支付接口。它通常用于记录外部系统已经完成的交易，不会调用 BigCommerce 的测试信用卡网关，也不会使用 4111111111111111 执行扣款。

典型流程如下：

Create Cart
→ Complete Checkout
→ Select Shipping Option
→ Create Order
→ Create Payment Access Token
→ Process Payment

创建订单前必须完成的 checkout 状态

调用以下接口前：

POST /api/storefront/checkouts/{checkoutId}/orders

应确认 checkout 已满足以下条件：

至少包含一个有效商品。
billingAddress 完整。
已填写访客结账所需的邮箱。
每个实体商品都有对应的 consignment。
每个需要配送的 consignment 都已选择 shippingOptionId。
商品、库存、配送地区和货币仍然有效。
checkout 中没有未解决的验证错误。

常见误区是，创建 consignment 后，接口返回了 availableShippingOptions，就认为系统已经选好了配送方式。实际上，还需要从返回结果中取得一个配送选项 ID，再更新 consignment。

例如：

PUT /api/storefront/checkouts/{checkoutId}/consignments/{consignmentId}
Content-Type: application/json

{
  "shippingOptionId": "YOUR_SHIPPING_OPTION_ID"
}

更新后应重新读取 checkout，确认对应的 consignment 中已经包含选定的配送方式，而不只是 availableShippingOptions。

调用 Checkout Order API

checkout 完整后，创建订单通常不需要提交信用卡号：

curl --request POST \
  "https://store.example.com/api/storefront/checkouts/CHECKOUT_ID/orders" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{}'

成功响应通常会包含新建订单的 orderId。具体的 HTTP 状态码和响应字段，请以当前商店版本对应的 BigCommerce 文档为准。

如果调用失败，应重点查看响应正文，不能只看状态码。常见原因包括：

consignment 尚未选择配送方式。
billing address 缺少必填字段。
访客 checkout 缺少 email。
checkout ID 与当前 storefront session 不匹配。
商品库存、价格或配送选项在提交前发生了变化。
请求使用了错误的主机或 API 类型。
Postman 请求没有携带浏览器 storefront session 所需的 cookie 或 CSRF 信息。

/api/storefront/... 是 Storefront API 路径，通常需要通过商店的 storefront 域名访问，而不是直接请求：

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

后者主要用于管理类 API，认证机制也与 Storefront API 不同。

Postman 中需要特别检查的认证问题

如果之前的 checkout 操作是在浏览器或移动应用中完成，而创建订单的请求改由 Postman 发起，需要确保所有请求都属于同一个 checkout 会话。

根据商店配置和调用方式，可能需要携带：

storefront session cookie；
X-XSRF-TOKEN 等 CSRF 请求头；
与 cookie 对应的 token；
正确的商店域名和 channel/site 上下文。

不能只是把浏览器请求中的 checkoutId 放进一个完全独立的 Postman 会话，就认为该 checkout 一定可以访问。

较稳妥的排查方式是：

在 Postman 中从创建 cart 开始，完整执行一次流程。
每一步都保存最新的 cart、checkout 和 consignment ID。
创建 consignment 后，读取 availableShippingOptions。
明确选择一个 shippingOptionId。
再次读取 checkout，确认地址和配送信息已经完整。
最后调用 POST /checkouts/{checkoutId}/orders。

订单创建后如何支付

订单创建完成并不代表支付已经完成。信用卡支付通常需要使用 BigCommerce Payments API，而不是 Orders API 中的 Create Transaction。

服务端需要先为订单创建 payment access token。示意请求如下：

curl --request POST \
  "https://api.bigcommerce.com/stores/STORE_HASH/payments/access_tokens" \
  --header "X-Auth-Token: STORE_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "ORDER_ID"
  }'

取得 payment access token 后，再向 Payments API 提交支付。具体请求结构取决于支付方式、网关和当前 API 版本，形式大致如下：

{
  "payment": {
    "instrument": {
      "type": "card",
      "number": "4111111111111111",
      "cardHolderName": "Test User",
      "expiryMonth": 12,
      "expiryYear": 2030,
      "verificationValue": "123"
    },
    "paymentMethod": {
      "id": "PAYMENT_METHOD_ID"
    }
  }
}

paymentMethod.id 不能随意填写，必须使用当前 checkout、channel 和支付配置实际提供的支付方式标识。完整字段仍应以当前 Payments API 文档和目标网关的要求为准。

出于安全考虑：

商店 API access token 只能保存在服务端。
不要将 payment access token 作为长期凭证保存。
生产环境中不要记录完整卡号或 CVV。
移动应用中不应包含 BigCommerce 管理 API 凭证。
正式处理信用卡前，需要确认应用架构符合相应的 PCI DSS 要求。

为什么不应使用 Create Transaction 完成测试支付

以下接口用于记录订单交易：

POST /stores/{store_hash}/v3/orders/{order_id}/transactions

它主要用于将外部支付系统产生的授权、扣款或退款记录关联到订单。调用该接口通常不会：

验证测试卡号；
调用 BigCommerce 中配置的支付网关；
对信用卡执行授权或扣款；
自动完成标准的 hosted payment flow。

如果需要验证 BigCommerce 的 test credit card payment，应使用受支持的 Payments API 或 BigCommerce Checkout SDK 支付流程。只有在支付已经由自己的外部支付服务完成，需要将结果同步回 BigCommerce 时，才应考虑创建 transaction 记录。

建议的最终实现方式

移动应用可以处理购物车和 checkout 交互，但敏感操作应交给自己的后端：

Mobile App
    │
    ├─ 创建及更新 cart/checkout
    │
    └─ 请求自己的后端提交订单
             │
             ├─ 创建 BigCommerce order
             ├─ 创建 payment access token
             └─ 调用受支持的支付流程

如果 Checkout Order API 仍然失败，以下信息最有助于诊断问题：

HTTP 状态码；
完整且已脱敏的错误响应；
创建订单前读取到的 checkout JSON；
每个 consignment 是否包含已选定的 shippingOptionId；
请求使用的域名、认证方式和关键请求头。

在缺少这些响应内容时，最可能漏掉的步骤是创建 consignment 后没有选择 shipping option。另一种常见情况是，Postman 没有复用正确的 storefront session。