1688 Cross-border Pay payment link API

Retrieve a cashier link; this does not charge an account, confirm payment, update a procurement order, or record GMV. Only 1688 is supported.

Request

Use POST /v1/orders/payment-link with channel: "1688", or POST /v1/orders/1688/payment-link with an optional channel that must be 1688 when supplied.

Requires a live key with order:create scope, plan access to 1688, and valid 1688 buyer authorization. The Gateway handles marketplace signing and access tokens. Successful requests cost 2 shared daily billable units per request, not per order.

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

order_ids must contain 1–30 distinct positive decimal strings without leading zeros, each at most 9223372036854775807. Recommend batches of at most 10. JSON numbers are rejected to prevent precision loss. Use native 1688 buyer order IDs, never warehouse procurement IDs or Sandbox fixture IDs.

In both fulfillment modes, this API calls 1688 directly with the app/mode’s selected buyer token. It cannot replace warehouse procurement payment or update warehouse order status.

Standard response

{
  "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 means link generation only. Excluded orders are listed in cant_pay_order_ids; a returned link does not imply every requested order can be paid. An explicit upstream rejection returns HTTP 200 with success: false, pay_url: null, and optional error_code / error_message. Upstream 400_4 means no requested order can use Cross-border Pay.

Standard mode accepts only HTTPS URLs on 1688.com or its subdomains, without URL credentials or nonstandard ports. Missing or unsafe links and malformed upstream results produce HTTP 502 CHANNEL_UPSTREAM_ERROR.

Raw format and Sandbox

Set response_format: "upstream" for the vendor envelope. upstream_api is com.alibaba.trade/alibaba.crossBorderPay.url.get. Unsafe Long integers are preserved as exact strings; otherwise vendor fields remain unchanged. Raw mode does not validate standard business results or cashier URLs, so consumers must validate them themselves.

Both routes reject hio_test_* with HTTP 400 SANDBOX_CAPABILITY_UNAVAILABLE. No real or simulated cashier link is produced, and no production payment upstream is called.

Invalid input returns HTTP 400 VALIDATION_ERROR; non-1688 channels return UNSUPPORTED_CHANNEL. Standard API authentication, scope, plan, and rate-limit errors also apply.

There is no payment Idempotency-Key replay on this link-generation API: each valid request retrieves a fresh link. Do not apply this retry behavior to actual payment submission. Do not log full cashier URLs. Link expiry is unspecified; confirm actual payment through the applicable order status query after checkout.

See procurement orders, actual payment submission, and Sandbox. Machine-readable contract: GET https://api.hiobuy.com/openapi.json.