1688 KJB 跨境宝支付链接 API

新接入统一采用 HIOBuy 托管采购与履约。自行采购、Self Fulfillment 和个人平台授权仅供获得管理员许可且订阅有效的既有应用继续使用。旧权限过期或被停用后不可使用,既有合作安排请联系支持核实。现有 API Endpoint 和历史订单继续保留。 旧订阅过期后,续费也不会重新开通旧模式。

本接口生成的是 1688 KJB(跨境宝,Cross-border Pay)支付链接,不是其他支付方式的通用付款链接。返回的 pay_url 用于打开符合跨境宝支付条件的 1688 订单收银台。接口只获取链接,不执行付款,不修改订单支付状态,也不会将订单记入采购 GMV。当前不支持淘宝或微店。

开通 1688 KJB 跨境宝

使用跨境宝付款前,需要在 WorldFirst(万里汇)开通跨境宝,并绑定、授权这些订单所属的 1688 买家账号。HioBuy API 授权不会替用户开通跨境宝。具体步骤请参阅 WorldFirst 官方跨境宝开通与使用指南(中文) 。

打开返回的收银台链接后,选择 担保交易 → 跨境宝,使用已绑定的 WorldFirst 账户完成付款。生成链接不代表所有订单都可使用跨境宝,仍需满足账号开通及订单可支付条件。开通条件、费用和支持地区以 WorldFirst 与 1688 最新规则为准。

需要排查订单是否支持跨境宝时,可先调用只读的可用支付渠道查询。查询只报告当前可用渠道,不保证生成链接或付款成功。

请求与权限

  • 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 校验,调用方应自行验证上游字段。

HTTP错误码说明
400VALIDATION_ERROR数量、格式、重复 ID 或响应格式错误。
400UNSUPPORTED_CHANNEL非 1688,或统一入口缺少渠道。
401INVALID_API_KEY / CHANNEL_NOT_AUTHORIZED密钥或渠道授权无效。
403INSUFFICIENT_SCOPEKey 不具备所需权限。
429PLAN_CHANNEL_DISABLED 或配额、限流错误套餐不支持该渠道、配额耗尽或请求频率超限。
502CHANNEL_UPSTREAM_ERROR上游 HTTP / JSON 异常,或标准模式下返回无效链接、无明确结果、无效 ID。

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

支付后的处理

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

获取支持

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

发送邮件