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
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
- Activate the caller: register the calling system through /terminal/activate and store terminal_sn + terminal_key; confirm target device binding separately.
- Push: call /appPush/tradePush. PUSH_SUCCESS only confirms push acceptance; obtain the payment order sn from a later query or notification.
- Customer Pays: Customer scans QR or presents card → terminal processes payment
- Receive Result: Callback to notify_url + optional proactive query via /upay/v2/query
- 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.
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.
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
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
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.
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.
