1688 跨境宝支付链接 API

根据真实 1688 订单获取跨境宝收银台链接。接口只获取链接，不执行付款，不修改订单支付状态，也不会将订单记入采购 GMV。当前不支持淘宝或微店。

请求与权限

• Base URL：https://api.hiobuy.com
• 统一入口：POST /v1/orders/payment-link，必须提供 channel: "1688"。
• 渠道入口：POST /v1/orders/1688/payment-link，可省略 channel；如提供，只能为 1688。
• 鉴权：Authorization: Bearer <hio_live_API_KEY>，需要 order:create scope。
• App 必须拥有有效的 1688 买家授权及套餐渠道权限。1688 开放平台应用也需要对应接口权限。
• 按现有订单批量 API 规则，成功请求消耗 2 个共享日配额计费单位，不是每个订单扣 2 个。

curl -X POST https://api.hiobuy.com/v1/orders/payment-link \
  -H 'Authorization: Bearer <hio_live_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"channel":"1688","order_ids":["151923545498520","151923545498521"]}'

Gateway 负责签名及渠道 token，不需要提交 1688 App Key、签名或 access token。订单 ID 以字符串保存，并以无损数字数组传给上游 orderIdList。

self 和 warehouse 模式均使用当前 App 对应的 1688 token 直接调用官方接口。这里只接受该买家账号下的原生 1688 订单 ID，不接受仓库采购单 ID；获取链接和打开收银台都不会改变仓库采购单状态。仓库采购单支付仍应走既有仓库采购支付流程，不能用本接口替代。订单归属、支付渠道和额度由上游校验。

标准响应

{
  "channel": "1688",
  "payment_method": "cross_border_pay",
  "success": true,
  "pay_url": "https://trade.1688.com/order/cashier.htm?orderId=151923545498520",
  "cant_pay_order_ids": [
    "151923545498521"
  ],
  "request_id": "req_example"
}

success 表示生成链接成功，不是支付成功。cant_pay_order_ids 列出因额度或风控等原因不能参与本次批量支付的订单。不要因返回链接就将全部输入订单标记为可支付或已支付。

上游明确拒绝时仍返回 HTTP 200，标准响应如下；客户端必须检查 success：

{
  "channel": "1688",
  "payment_method": "cross_border_pay",
  "success": false,
  "pay_url": null,
  "cant_pay_order_ids": [],
  "error_code": "400_4",
  "error_message": "无可使用支付渠道[跨境宝]付款的订单",
  "request_id": "req_example"
}

400_4 表示没有可用跨境宝付款的订单，应检查订单与支付渠道。其他上游业务错误通过 error_code / error_message 返回（上游未提供时省略）。

标准响应只接受 HTTPS 的 1688.com 或其子域名收银台链接，不允许 URL 用户名、密码或非标准端口。上游返回其他域名时暂按异常处理，需核实官方契约后再扩展；不要自行拼接或替换支付链接。

原始响应

设置 response_format: "upstream" 可得到 channel、response_format、upstream_api、upstream 和 request_id。upstream_api 为 com.alibaba.trade/alibaba.crossBorderPay.url.get，upstream 保留官方字段，包括布尔或字符串形式的 success。超过 JavaScript 安全整数范围的 Long 数字会转换为精确字符串，避免响应订单 ID 被舍入。原始模式不执行标准结果或 URL 校验，调用方应自行验证上游字段。

错误与 Sandbox

本接口没有付款操作的 Idempotency-Key 回放能力；每次有效请求都会重新获取链接。不要将此行为用于真实付款 API 的自动重试。

支付后的处理

使用订单详情或适用的官方支付状态查询确认实际支付结果，再更新业务状态。链接有效期未由上游资料定义，不能假设固定 TTL。完整支付链接不应写入日志或分析事件；Gateway 请求日志会对标准 pay_url 和原始 payUrl 脱敏。

相关文档：采购订单、执行付款、Sandbox。机器可读规范：GET https://api.hiobuy.com/openapi.json。