1688 订单可用支付渠道 API

查询单个原生 1688 买家订单当前支持的支付渠道，方便用户排查 KJB 跨境宝支付资格。它是只读查询，与生成跨境宝支付链接、执行支付是不同操作，不修改、取消订单，不确认付款，也不计入采购 GMV。

请求与权限

• Base URL：https://api.hiobuy.com
• 统一入口：POST /v1/orders/payment-methods，必须提供 channel: "1688"。
• 渠道入口：POST /v1/orders/1688/payment-methods，可省略 channel；提供时只能是 1688。
• 需要 Live Key（hio_live_*）、order:read 权限、可用的 1688 套餐配额和有效的买家授权。
• 授权账号必须是订单买家，且必须为买家主账号；上游 500_2 表示没有权限，应检查授权买家和主账号身份。
• 1688 access token、签名、时间戳由 Gateway 处理，不要在请求体传渠道密钥。
• 成功 HTTP 请求消耗 1 个共享日计费单位，不是各渠道单独一份配额。

curl -X POST 'https://api.hiobuy.com/v1/orders/payment-methods' \
  -H 'Authorization: Bearer YOUR_HIOBUY_LIVE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"channel":"1688","order_id":"239695213738498520"}'

标准响应

以下为结构示例，不是真实客户订单，也不表示所有订单都支持跨境宝。

{
  "channel": "1688",
  "success": true,
  "order_id": "239695213738498520",
  "channels": [
    {
      "code": 1,
      "name": "支付宝"
    },
    {
      "code": 20,
      "name": "跨境宝"
    }
  ],
  "payment_amount": {
    "amount": 32120,
    "currency": "CNY"
  },
  "payment_deadline": "2018-11-04 14:00:45",
  "monetary_unit": "CNY_minor",
  "request_id": "req_example"
}

支付渠道编码

以下为上游契约提供的 1688 编码，不能直接当作 HioBuy 支付接口的 pay_channel 参数使用。

16、20 都标为跨境宝。17 是红包，35 是网商银行跨境直采，不能当作跨境宝处理；以实际返回的编码和名称为准。

用户如何排查跨境宝

1. 使用订单所属买家主账号的授权，查询该未付款原生订单。
2. 先检查 success；若返回 500_2，先解决买家授权或主账号权限，不能将错误当作订单不支持跨境宝。
3. 查询成功且包含 16 或 20 时，可继续调用跨境宝支付链接 API。查询结果不保证生成链接或付款一定成功，仍以链接接口与收银台实时结果为准。
4. 查询成功但没有跨境宝或列表为空，表示本次查询未报告该订单当前可使用跨境宝；请向 1688 / WorldFirst 核对账号与订单资格，不应直接认定 HioBuy 支付链接接口异常。
5. 订单详情中的 pay_channels 为空，不替代本查询接口的结果。建议保留查询结果、生成链接结果及两次 request ID 联系支持。

本接口不能判断开通后旧订单是否一定支持跨境宝，也不能确定是否需要重建订单。不要仅因没有渠道或查询失败就自动取消订单。开通方式参阅 WorldFirst 官方中文指南 。

业务失败与 HTTP 错误

上游业务拒绝保留为 HTTP 200、success: false：

{
  "channel": "1688",
  "success": false,
  "order_id": "239695213738498520",
  "channels": [],
  "payment_amount": null,
  "payment_deadline": null,
  "error_code": "500_2",
  "error_message": "没有权限获取该订单可支付方式。",
  "monetary_unit": "CNY_minor",
  "request_id": "req_example"
}

上游格式

传 response_format: "upstream"，返回上游包络。upstream_api 为 com.alibaba.trade/alibaba.trade.payWay.query；upstream 保留 success、errorCode、errorMsg 和 resultList.channels/orderId/payFee/timeout。仍要检查 upstream.success，不能只看 HTTP 200。

超过 JavaScript 安全整数范围的整数字面量保留为精确字符串，避免大订单号失真；payFee 仍为分。标准格式遇到金额或渠道编码超过安全整数范围会报错，不四舍五入。

履约模式与 Sandbox

self 与仓库采购模式均使用当前 App / 模式选择的买家 token 直连 1688 查询，只接受原生 1688 订单号；不调用仓库采购支付接口。

Sandbox 返回 HTTP 400 SANDBOX_CAPABILITY_UNAVAILABLE，不编造真实支付资格，也不访问 Live 订单。重复查询读取实时上游信息，不使用支付幂等回放；正常鉴权、配额计费和请求日志仍保留，但不写订单、付款或 GMV 记录。

OpenAPI：GET https://api.hiobuy.com/openapi.json。