如何通过 BigCommerce API 创建已完成付款的订单？

2026-10-24支付小周

结论

不能直接写入或更新订单的 payment_status。这是一个只读字段，BigCommerce 会根据订单关联的支付交易计算其状态。

创建“已付款”订单通常有两种方式：

通过 BigCommerce Payments API 实际完成扣款，支付状态会由平台自动更新。
如果款项已在外部系统收取，先创建订单，再通过 Order Transactions API 记录一笔成功的 purchase 或 capture 交易。

修改订单的 status_id、payment_method 或其他普通字段，无法可靠地将 payment_status 设为已完成。

记录外部已完成的付款

如果款项已通过外部支付系统、线下收款或其他支付网关收取，可以先创建订单。

POST /stores/{store_hash}/v2/orders
X-Auth-Token: {access_token}
Content-Type: application/json
Accept: application/json

示例请求：

{
  "customer_id": 0,
  "billing_address": {
    "first_name": "San",
    "last_name": "Zhang",
    "street_1": "No. 1 Example Road",
    "city": "Shanghai",
    "state": "Shanghai",
    "zip": "200000",
    "country": "China",
    "country_iso2": "CN",
    "email": "customer@example.com"
  },
  "products": [
    {
      "product_id": 123,
      "quantity": 1
    }
  ],
  "payment_method": "External Payment"
}

从响应中取得订单 ID，然后为该订单创建交易记录：

POST /stores/{store_hash}/v3/orders/{order_id}/transactions
X-Auth-Token: {access_token}
Content-Type: application/json
Accept: application/json

如果外部系统已经完成授权和扣款，可以记录 purchase 事件：

{
  "event": "purchase",
  "method": "credit_card",
  "amount": 99.00,
  "currency": "CNY",
  "gateway": "external",
  "gateway_transaction_id": "PAY-20260902-0001",
  "test": false
}

各字段的含义如下：

event: "purchase" 表示购买交易已经完成。
amount 应与实际收到的金额一致。
currency 应与订单币种一致。
gateway_transaction_id 应填写外部支付平台返回的唯一交易编号，以便对账并防止重复提交。
test 应根据这笔交易是否属于测试交易设置。

如果业务流程是先授权、后扣款，应按照实际支付过程分别记录 authorization 和 capture，不能把尚未扣款的授权交易记为 purchase。

通过 BigCommerce 完成实际付款

如果外部系统尚未收款，不要为了改变订单状态而创建虚假交易。此时应使用 BigCommerce 支持的支付流程：

创建订单。
获取该订单对应的支付访问令牌。
调用 Payments API，提交支付工具和支付网关要求的信息。
支付网关成功完成交易后，BigCommerce 会更新订单的支付状态。

具体请求结构取决于店铺启用的支付网关及其支持的支付方式，无法用一套通用支付参数覆盖所有网关。实现时应以当前店铺和 API 版本返回的支付方法配置为准。

订单状态不等于付款状态

订单的业务状态和付款状态是两套独立的状态：

status_id 表示订单处于待处理、待发货、已完成或已取消等业务阶段。
payment_status 表示付款是否已授权、已捕获、部分退款或已退款等。

因此，即使把订单改为“已完成”或“待发货”，也不代表 BigCommerce 已确认收到付款。例如：

{
  "status_id": 10
}

这类更新只会改变订单状态，不能作为支付确认操作。具体的状态 ID 还可能受到店铺订单状态配置的影响，因此在查询店铺状态列表之前不应硬编码。

验证结果

创建交易后，可以重新读取订单：

GET /stores/{store_hash}/v2/orders/{order_id}
X-Auth-Token: {access_token}
Accept: application/json

还应查询订单交易列表进行核对：

GET /stores/{store_hash}/v3/orders/{order_id}/transactions
X-Auth-Token: {access_token}
Accept: application/json

验证时应以交易记录和重新读取的订单数据为准，不能仅凭创建交易的请求成功，就认定订单已经处于预期的付款状态。

注意事项

不要在创建或更新订单时提交 payment_status。即使请求中包含该字段，也可能被忽略或触发验证错误。
Order Transactions API 用于记录交易事实，不一定会调用外部网关扣款。只有确实收到款项后，才能记录成功的 purchase 或 capture。
如果交易金额不足，订单可能显示为部分付款，而非完整付款。
退款、撤销和拒付应通过对应的交易事件或实际支付网关处理，不能只修改订单状态。
为避免重复记账，应对 gateway_transaction_id 实施幂等控制，并在重试前查询已有交易。
API 可用字段以及允许使用的 event、method、gateway 值，可能因接口版本和店铺支付配置而异。提交前应核对当前 BigCommerce API 文档中的 Order Transactions 请求 schema。

payment_status 不能直接设置。应完成或登记相应的支付交易，再由 BigCommerce 根据交易结果生成付款状态。