Pay procurement order API

To retrieve a 1688 Cross-border Pay cashier URL without submitting payment, use the separate payment link API.

Use one of these equivalent routes:

• POST /v1/orders/pay — body requires channel
• POST /v1/orders/1688/pay — body may omit channel
• POST /v1/orders/taobao/pay — body may omit channel

Optional idempotency header

Idempotency-Key is optional but recommended for every logical payment. Generate a new unique value when the user starts a payment, persist it with that payment attempt, and reuse the same value only when retrying the same request.

POST /v1/orders/pay
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: 6c14ce20-cf29-4c25-a9ee-3d36aac94c16
 
{"channel":"1688","order_id":"1234567890"}

The header is implemented by the HIOBuy Gateway; marketplace support is not required.

Do not solve PAYMENT_RESULT_UNKNOWN by generating a new key: the marketplace may already have charged the order.

Request body

Response

StandardOrderPayResult — response model.

Always check the response body as well as HTTP status because a marketplace business refusal can be returned as HTTP 200 with success: false.

Taobao self-procurement payment confirmation

The official Taobao FAQ describes this API as asynchronous payment submission. will_pay_purchase_order_ids lists submitted orders, while pay_failure_purchase_order_ids lists orders rejected before submission. For standard responses in Taobao self mode, the Gateway queries the order once after an unconfirmed payment call. success: true is returned only when that query confirms a paid order state. Neither official code: "0" nor the submitted list proves completed payment.

Evaluate the requested order, not the entire batch: its failure details take priority; a submitted order without its own rejection must be confirmed by query. An aggregate BATCH_PAY_ERROR may coexist with submitted orders and must not, by itself, mark the requested order as failed. Missing per-order evidence remains unconfirmed.

The following optional fields are additive; existing field names/types and other channels/modes remain unchanged:

Do not automatically start another payment or switch keys for pending/unknown. Query order detail or retry with the same Idempotency-Key. Unconfirmed, legacy, transport-unknown, and stale Taobao self standard replays refresh order status without another payment call. Verified results are written back to the existing idempotency record, so confirmed success will not regress to pending when a later query fails. Idempotency completion means the HTTP operation finished, not that payment settled.

The response body retains the original logical request_id; the response-header x-request-id identifies the current HTTP request, including a reconciliation replay. Send both when asking for support.

After an explicit rejection, correct its cause and confirm the order is still payable before starting a new logical attempt using a new key. For an unresolved attempt, a human must verify marketplace payment records/account transactions and confirm the previous attempt has ended without payment or deduction before submitting one new attempt. An unpaid order or the absence of an immediate debit alone is not sufficient. Reusing the old key never submits payment again. The Gateway does not automatically retry payment, expire a key to permit another debit, or remove old idempotency records. For 1688, if you explicitly supply op_request_id, also use a new upstream identifier for the new logical attempt.

Recovery guidance {#recovery-guidance}

payment_recovery contains action, reason, and, when available, elapsed_seconds measured from the original attempt rather than the latest retry.

Reasons are PAYMENT_CONFIRMED, PAYMENT_REJECTED, AWAITING_CONFIRMATION, SUBMISSION_UNCONFIRMED, CONFIRMATION_OVERDUE, and ORDER_CLOSED.

For keyed Taobao self standard attempts, unresolved confirmation lasting 15 minutes changes the outcome to payment_status: "unknown" with manual_review / CONFIRMATION_OVERDUE. The existing pending: true still means not confirmed, not that an official job is running. This threshold is a Gateway support hint, not an official payment SLA, expiry, or proof of failure; it does not clear the key or resubmit payment. A closed order requires manual review and is not treated as proof of failed payment.

{
  "channel": "taobao",
  "order_id": "200000017003",
  "success": false,
  "pending": true,
  "payment_status": "unknown",
  "payment_submission_status": "submitted",
  "order_status": "wait_payment",
  "payment_recovery": {
    "action": "manual_review",
    "reason": "CONFIRMATION_OVERDUE",
    "elapsed_seconds": 900
  },
  "request_id": "req_example_original"
}

response_format=upstream remains raw vendor JSON without automatic confirmation; callers must query order detail themselves.