支付代购订单 API

如需获取 1688 跨境宝收银台链接而不直接执行付款，请使用独立的 支付链接 API。获取链接不表示订单已支付。

以下路径能力相同：

  • POST /v1/orders/pay — body 必须传 channel
  • POST /v1/orders/1688/pay — body 可省略 channel
  • POST /v1/orders/taobao/pay — body 可省略 channel

可选幂等请求头

每次逻辑支付建议携带 Idempotency-Key。用户发起新支付时生成一个唯一值并保存；只有重试同一请求时才复用。

POST /v1/orders/pay
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: 6c14ce20-cf29-4c25-a9ee-3d36aac94c16
 
{"channel":"1688","order_id":"1234567890"}

此能力由 HIOBuy Gateway 实现，不要求渠道上游支持。

情况结果
首次请求Gateway 执行支付并保存结果
相同 key + 相同标准化参数回放原结果；响应头含 Idempotency-Replayed: true
相同 key + 不同参数HTTP 409 IDEMPOTENCY_CONFLICT
首次请求仍在执行HTTP 409 IDEMPOTENCY_REQUEST_IN_PROGRESS；等待 error.details.retry_after_ms 后用原 key 重试
之前的上游结果不确定通常 HTTP 409，并附 error.details 恢复指引；淘宝 self 标准同 Key 改为只读查询，返回当前标准结果

不要通过更换 key 绕过 PAYMENT_RESULT_UNKNOWN，因为渠道可能已经完成扣款。

请求体

字段必填说明
channel仅统一路径必填1688 | taobao
order_id是创建 返回的主单 order_id
pay_channel1688 选填如 Alipay / kjpayV2
pay_amount1688 选填支付总额，人民币分
op_request_id1688 选填上游历史请求标识；Gateway 全链路重试保护优先使用 Idempotency-Key

响应

StandardOrderPayResult — 字段见 响应模型。部分渠道业务拒绝可能以 HTTP 200 + success: false 返回，因此还需检查响应体。

支付确认与恢复 {#recovery-guidance}

淘宝 self 标准模式只有订单查询确认付款后才返回 success: true；code: "0" 或旧成功结果不是扣款证明。pending 是网关未确认，不是官方处理队列状态。

Idempotency-Key 是可选 HTTP 请求头。同一次付款重试复用原 Key；新 Key 是新的真实付款尝试，不应自动生成来绕过未确认结果。

新增选填字段:

  • payment_submission_status: submitted / rejected / unknown.
  • payment_recovery: action, reason, elapsed_seconds.
action支付确认与恢复
none无须再付款
query_order查询订单或复用原 Key
retry_with_new_key官方明确拒绝后，修正原因并确认订单仍可付款，再发起一次新尝试
manual_review人工核对官方支付记录及账户流水，不自动重付

原始 Key 请求超过 15 分钟仍未确认时为 unknown / manual_review / CONFIRMATION_OVERDUE。该阈值不是官方失败或到期证明，不解锁 Key 或重新扣款。同 Key 的旧结果、超时和停滞请求只查询；确认成功会写回。仅待付款或暂未扣款不足以重试：人工确认前次尝试已结束且未支付、未扣款后，才可用新 Key 提交一次新付款。

响应体 request_id 是原付款，响应头 x-request-id 是本次 HTTP 请求。upstream、沙箱和仓库模式不变。1688 明确 paySuccess 时也提供恢复指引；新尝试如显式传 op_request_id，也需用新标识。

获取支持

需要集成帮助？请联系开发者支持 support@hiobuy.com · 预计 1–2 个工作日内回复

发送邮件