1688 order payment methods API

Эта новая страница пока доступна на английском языке.

Query the payment channels currently available for one native 1688 buyer order, primarily to help developers diagnose KJB (Cross-border Pay) eligibility. This is a read-only query, separate from generating a KJB cashier link or submitting payment. It does not change orders, cancel them, confirm payment, or record procurement GMV.

Request and prerequisites

• Base URL: https://api.hiobuy.com
• Unified endpoint: POST /v1/orders/payment-methods; requires channel: "1688".
• Shortcut: POST /v1/orders/1688/payment-methods; channel is optional, but must be 1688 if supplied.
• Use a live hio_live_* key with order:read, enabled 1688 plan access, and valid 1688 buyer authorization.
• The authorized user must be the order’s buyer main account. Vendor error 500_2 indicates no permission; check the authorized buyer and whether it is the main account.
• Gateway handles the upstream access token, signing and timestamp. Do not send marketplace credentials in this request.
• Successful HTTP requests cost 1 shared daily billable unit, not one separate allowance per marketplace.

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"}'

Standard response

The following is illustrative, not a real customer order or a guarantee that KJB is available.

{
  "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"
}

Payment channel codes

These are 1688 vendor codes, not values to pass directly as HioBuy pay_channel. Names below follow the supplied upstream contract.

Codes 16 and 20 are listed as KJB / 跨境宝. Do not treat 17 (red envelope) or 35 (a separate bank cross-border procurement product) as KJB. Preserve the actual returned code and name rather than translating unknown codes into another method.

Troubleshooting KJB eligibility

1. Query the exact unpaid native order using the same authorized buyer main account used for that order.
2. Check success first. For 500_2, correct buyer authorization/main-account access before interpreting channels.
3. When a successful query includes 16 or 20, try the KJB payment-link API for that order. Query results do not guarantee that link generation or checkout will succeed; eligibility can change.
4. If a successful query lacks KJB or returns no channels, this query has not reported KJB as available for that order at that moment. Check account/order eligibility with 1688/WorldFirst; do not infer that HioBuy’s payment-link integration is broken.
5. An empty pay_channels in order detail is not a replacement for this dedicated query. Keep the query result, payment-link result and request IDs for support.

This API cannot determine whether activation will make an existing order eligible or whether a new order is necessary. Do not automatically cancel orders based only on missing channels or a failed query. See the official WorldFirst KJB activation guide .

Errors and upstream format

Vendor business rejection returns HTTP 200 with success: false. For example:

{
  "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"
}

Set response_format: "upstream" for the upstream response envelope. It contains upstream_api: "com.alibaba.trade/alibaba.trade.payWay.query" and the vendor payload under upstream, retaining success, errorCode, errorMsg, and resultList.channels/orderId/payFee/timeout. Check upstream.success, not just HTTP status. Unsafe integer JSON tokens are preserved as exact strings, including large order IDs; payFee remains in fen. Standard format rejects unsafe amount/channel-code integers instead of rounding them.

Fulfillment modes, Sandbox and side effects

In both self and warehouse procurement modes, Gateway queries 1688 directly with the app/mode’s selected buyer token. Only native 1688 order IDs are accepted; this is not a warehouse procurement payment operation.

Sandbox keys return HTTP 400 SANDBOX_CAPABILITY_UNAVAILABLE. Sandbox does not simulate real payment eligibility or access live order data.

There is no payment idempotency replay: repeated queries read current upstream information. The operation writes no order state or payment/GMV records; normal authentication, quota accounting and request logging still apply.

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