如何获取沙箱支付的支付状态？

2026-10-24支付小周

结论

要获取沙箱支付状态，通常需要调用支付平台的“支付订单查询”或“交易查询”接口。沙箱一般沿用正式环境的接口定义，只需将请求地址、应用凭证和商户信息换成沙箱配置。

由于没有指定支付平台，无法给出确切的 API 名称和请求路径。可以在对应平台的文档中搜索：

查询支付订单
查询交易
Payment Query
Retrieve Payment
Get Payment Status

推荐处理流程

1. 保存支付订单号

创建沙箱支付订单后，保存接口返回的平台交易号或请求中使用的商户订单号。后续查询支付状态时，通常至少需要其中一个。

常见字段有：

out_trade_no
trade_no
transaction_id
payment_id
order_id

应以实际支付平台的接口文档为准，确认需要使用哪个字段。

2. 调用订单查询接口

下面是一个通用请求示例。域名、路径和参数都是占位符，不能直接用于生产代码：

curl -X GET \
  "https://sandbox.example.com/v1/payments/PAYMENT_ID" \
  -H "Authorization: Bearer SANDBOX_ACCESS_TOKEN" \
  -H "Accept: application/json"

有些平台使用 POST 请求，并根据商户订单号查询：

curl -X POST \
  "https://sandbox.example.com/v1/payments/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SANDBOX_ACCESS_TOKEN" \
  -d '{
    "out_trade_no": "TEST_ORDER_202609090001"
  }'

返回结果可能类似：

{
  "order_id": "TEST_ORDER_202609090001",
  "status": "SUCCESS"
}

各平台的状态值并不统一，常见形式包括：

PENDING
PROCESSING
SUCCESS
FAILED
CLOSED
REFUNDED

这些状态仅用于举例。不要自行固定状态枚举，应按照实际平台文档进行处理。

3. 同时接收异步通知

订单查询可用于主动确认支付结果，但正常业务流程不能只依赖前端跳转结果。还应配置支付结果通知地址：

notify_url=https://your-domain.example/payment/notify

服务端收到通知后，需要：

验证签名或通知来源。
校验商户订单号、金额和币种。
检查订单是否已经处理。
更新本地订单状态。
按平台要求返回确认响应。

如果长时间没有收到通知，再调用订单查询接口主动补查。

服务端查询示例

下面的 Node.js 示例展示了一种通用实现。接口地址和鉴权方式需要替换为实际支付平台的配置：

async function queryPayment(paymentId) {
  const response = await fetch(
    `https://sandbox.example.com/v1/payments/${encodeURIComponent(paymentId)}`,
    {
      method: "GET",
      headers: {
        Authorization: `Bearer ${process.env.SANDBOX_ACCESS_TOKEN}`,
        Accept: "application/json"
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Payment query failed: HTTP ${response.status}`);
  }

  const result = await response.json();

  switch (result.status) {
    case "SUCCESS":
      return "PAID";
    case "FAILED":
    case "CLOSED":
      return "UNPAID";
    case "PENDING":
    case "PROCESSING":
      return "PENDING";
    default:
      return "UNKNOWN";
  }
}

业务系统可以定义统一的内部状态，例如 PAID、UNPAID 和 PENDING，再将支付平台返回的状态映射到这些状态。这样可以避免业务逻辑直接依赖第三方的状态值。

找不到接口时重点检查

当前查看的是支付产品文档，还是开放平台通用文档。
应用是否已开通沙箱支付能力。
请求是否使用了沙箱网关和沙箱凭证。
查询接口是否位于“订单”“交易”或“支付结果”目录。
创建支付订单时是否取得了可供查询的订单号。
SDK 是否提供 query、retrieve、getPayment 或 getTransaction 等方法。
沙箱是否支持所选支付产品。部分平台提供的沙箱能力可能不完整。

注意事项

不要根据前端页面、支付跳转结果或客户端回调直接认定支付成功。最终状态应通过服务端异步通知或服务端订单查询结果确认。

查询接口需要设置合理的超时和重试策略。遇到 PENDING 或 PROCESSING 状态时，可以间隔数秒后重试，但不要连续轮询，以免触发限流。

沙箱订单与正式环境订单通常相互隔离。使用正式环境的网关或凭证查询沙箱订单，往往只会得到“订单不存在”或鉴权失败，无法取得正确的支付状态。