For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/business.md.
  • English
  • Business Guide

    Complete Integration Journey

    From application to first transaction — a phased walkthrough of the entire onboarding and integration lifecycle

    Phase 1 · Preparation

    Phase 2 · Terminal Binding

    Phase 3 · API Integration

    Quick Checklist (for reference)

    Complete merchant/device setup and obtain caller credentials; verify raw-byte signing, first payment, queries, notifications and refunds; pass failure scenarios and the launch checklist before production.

    End-to-End Integration Flow

    Complete payment lifecycle in a push-order scenario

    1. Activate the caller: register the calling system through /terminal/activate and store terminal_sn + terminal_key; confirm target device binding separately.
    2. Push: call /appPush/tradePush. PUSH_SUCCESS only confirms push acceptance; obtain the payment order sn from a later query or notification.
    3. Customer Pays: Customer scans QR or presents card → terminal processes payment
    4. Receive Result: Callback to notify_url + optional proactive query via /upay/v2/query
    5. Refund (if needed): Call /upay/v2/refund → confirm via query → update merchant system

    Order Status Flow

    Cancellation states: CANCELED / PAY_CANCELED.

    This diagram shows the payment/refund path, not every possible state or transition. Order state can change after payment or partial refund. Inspect transaction type and status as well; see Response and State Handling.

    Response and State Handling

    Evaluate all four layers in order. Missing fields, unknown enums and invalid signatures leave the outcome unconfirmed; do not default to success or failure.

    LayerField / ExampleMeaning
    HTTPHTTP 2xxAn HTTP response arrived; authentication errors may also use HTTP 200.
    API resultTop-level result_code = "200" / "400" / "500"Business response available / request error / service error. This layer or a network timeout alone cannot establish the financial outcome.
    Business resultbiz_response.result_codePUSH_SUCCESS / MIS_PUSH_SUCCESS acknowledge acceptance. Query SUCCESS means the query ran. Server refunds use REFUND_*. Also inspect error_code.
    Transaction resultbiz_response.data.type / status / order_statusMatch merchant, client_sn/sn, total_amount and transaction type. Example of payment success: PAYMENT + SUCCESS + PAID. Track subsequent refunds separately.

    Orders and Transactions

    sn identifies the order; tsn identifies a transaction. One order can have a PAYMENT followed by multiple REFUND transactions or a CANCEL. Without refund_request_no, a query can return the latest refund. Interpret status=SUCCESS together with type.

    order_statusAction
    CREATEDPayment unconfirmed; wait and query.
    PAIDPaid; fulfill idempotently. Later refunds/reversals remain possible.
    PARTIAL_REFUNDED / REFUNDEDPartial/full refund. Check the specific refund transaction; do not record a new payment.
    PAY_CANCELED / CANCELEDPayment closed, or order canceled/reversed. CANCELED can also result from actively closing an unpaid order. Neither enum alone proves a previous charge or returned funds; check the original payment/cancellation transactions, amounts and channel result.
    PAY_ERROR / REFUND_INPROGRESS / REFUND_ERROR / CANCEL_INPROGRESS / CANCEL_ERRORKeep the operation pending or unconfirmed; query or escalate. An error state alone is not permission to collect or refund again.

    Transaction status can include CREATED, IN_PROG, PRE_SUCCESS, ERROR_RECOVERY, ABORTING, SUCCESS, FAIL_CANCELED, ABORTED, FAIL_ERROR and REFUND_ERROR. Do not implement only SUCCESS/FAIL or treat unknown values as final.

    Accepted Close Still in Progress

    {
      "result_code": "200",
      "biz_response": {
        "result_code": "MIS_PUSH_SUCCESS",
        "error_code": "ORDER_CLOSE_ABORT_IN_PROGRESS"
      }
    }

    Continue querying the original order. This response does not prove cancellation. Track payment, refund and cancellation outcomes separately and reject state regression from delayed events.

    Best Practices

    AreaRecommendation
    Activation ManagementSecurely persist caller terminal_sn / terminal_key; manage activation separately from target-device binding.
    Key rotationCall /terminal/checkin according to the integration configuration and update the key atomically; no universal daily frequency is assumed.
    Order Number UniquenessKeep out_trade_no unique within the merchant. Preserve the original ID for the same business operation; query unknown outcomes before another collection.
    Dual ConfirmationUse both notifications and queries; do not overwrite distinct transactions or regress confirmed state with an old event.
    Exception HandlingOn network timeout, query order status before retrying. Never blindly resend.
    ReconciliationReconcile payments, refunds and statements by merchant, store and business date; /mis/shift does not confirm settlement of funds.
    LoggingLog redacted business IDs, request time, states and error codes. Exclude keys, full card numbers and sensitive payloads.
    IdempotencyDeduplicate notifications by transaction and state. Assign an ID to each new refund; preserve it while its outcome is unknown.

    Timeouts, Duplicates and Recovery

    A client timeout means no trusted outcome was received. Keep a separate unconfirmed state, retain the original business IDs and suspend another collection or refund.

    TriggerImmediate ActionRecovery / Stop Condition
    Push timeout, disconnect, 5xx or invalid response signatureRetain out_trade_no and original parameters. Query by client_sn, or sn when available. Do not change order ID, device or channel to collect again.Fulfill idempotently when query/verified notification confirms payment; otherwise keep investigating.
    No order found shortly after push acceptanceThe device may not have created a payment transaction. Check merchant binding and wait for the payment flow.Not found does not prove rejection. Reissue only after confirming the original operation can no longer execute.
    Pending / recovery stateKeep the original order, use bounded backoff and await notifications.Suggested client intervals: 2, 5, 10 seconds, then low-frequency checks. This is integration guidance, not a platform rate or timing guarantee. Checkout timeout becomes pending reconciliation, not payment failure.
    Refund timeout / REFUND_IN_PROGRESS / REFUND_ERRORQuery original sn/client_sn + refund_request_no. Do not replace the ID or switch refund routes.Record only the confirmed refund; after a definite failure follow business rules, and escalate prolonged uncertainty.
    Close races with paymentRetain both records; query on ORDER_CLOSE_ABORT_IN_PROGRESS.Use confirmed order/transaction states. If collected funds were not reversed, follow the enabled refund process.
    Duplicate or out-of-order notificationVerify and persist; track effects by merchant/order + type + tsn + status and update local business state atomically.Do not discard a later refund under the same sn or overwrite it with an old PAYMENT notification.
    Rate limit or service/channel outageReduce concurrency and back off. Query existing operations before retrying money-moving requests.Resume reconciliation after recovery; no unbounded loops or mass re-submission.

    Idempotency Limits

    No universal Idempotency-Key header, retention window or replay of the original response is confirmed for these APIs. Merchant order uniqueness, refund business identity and your own atomic accounting are separate controls. Use a new ID for a new business operation, not to recover an unknown outcome.

    Time and Reconciliation

    Millisecond timestamps are Unix time. Use Asia/Singapore (UTC+08:00) explicitly for local display. Confirm business/accounting dates, cutoff times, statement format, refund posting and settlement cycles during setup. Link merchant/platform orders, transactions and business dates. net_amount is not net settlement income, and /mis/shift does not prove bank settlement.