> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Business Guide ## Complete Integration Journey \{#integration-journey} From application to first transaction — a phased walkthrough of the entire onboarding and integration lifecycle ### Phase 1 · Preparation ```mermaid flowchart LR accTitle: Phase 1 - Preparation accDescr: Submit an application, obtain service provider credentials after approval, and onboard the merchant. A["Step 1 · Submit Application

Submit company information,
contacts and tech stack
to platform support

ISV → AiMT
Output: Approval"] B["Step 2 · Get Credentials

AiMT issues credentials
after application approval

AiMT → ISV
Output: vendor_sn · vendor_key
app_id · app_key"] C["Step 3 · Merchant Onboarding

ISV submits merchant details;
AiMT registers the store
and generates store_sn

ISV → AiMT
Output: merchant_sn · store_sn"] A --> B --> C classDef preparation fill:#fffbeb,stroke:#d97706,color:#78350f class A,B,C preparation ``` ### Phase 2 · Terminal Binding ```mermaid flowchart LR accTitle: Phase 2 - Terminal Binding accDescr: AiMT binds the target payment device and generates the activation code. Use the target device ID in step 7. D["Step 4 · Bind POS Terminal

Bind target_device_id
to the store

Actor: AiMT
Output: target_device_id
Used for order push in step 7"] E["Step 5 · Get Activation Code

AiMT generates an activation
code linking store and device

Actor: AiMT
Output: code"] D --> E classDef binding fill:#eff6ff,stroke:#2563eb,color:#1e3a8a class D,E binding ``` ### Phase 3 · API Integration ```mermaid flowchart LR accTitle: Phase 3 - API Integration accDescr: Activate the ISV caller, push to the bound payment device, then manage transactions through refunds, queries and callbacks. F["Step 6 · Activate Terminal

Call /terminal/activate
to register the ISV device
as the platform API caller

Action: API call
Output: terminal_sn
terminal_key"] G["Step 7 · Push Order

Call /appPush/tradePush
using target_device_id
from step 4 to display on POS

Action: API call
Output: out_trade_no
Await payment; obtain sn
from a query or notification"] H["Step 8 · Other Operations

Refund, query and verify
callbacks throughout
the transaction lifecycle

Action: API call
APIs: /upay/v2/refund
/upay/v2/query · Callback"] F --> G --> H classDef integration fill:#f0fdf4,stroke:#16a34a,color:#14532d class F,G,H integration ``` :::info 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 \{#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 ```mermaid flowchart TD accTitle: Payment and refund order states accDescr: A created order can become paid, then fully or partially refunded. A partially refunded order can have further refunds. CREATED --> PAID PAID --> REFUNDED PAID --> PARTIAL_REFUNDED PARTIAL_REFUNDED --> PARTIAL_REFUNDED PARTIAL_REFUNDED --> REFUNDED ``` 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-states). ## Response and State Handling \{#response-states} Evaluate all four layers in order. Missing fields, unknown enums and invalid signatures leave the outcome unconfirmed; do not default to success or failure. | Layer | Field / Example | Meaning | | ------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP | HTTP 2xx | An HTTP response arrived; authentication errors may also use HTTP 200. | | API result | Top-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 result | biz_response.result_code | PUSH_SUCCESS / MIS_PUSH_SUCCESS acknowledge acceptance. Query SUCCESS means the query ran. Server refunds use REFUND\_\*. Also inspect error_code. | | Transaction result | biz_response.data.type / status / order_status | Match 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_status | Action | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | CREATED | Payment unconfirmed; wait and query. | | PAID | Paid; fulfill idempotently. Later refunds/reversals remain possible. | | PARTIAL_REFUNDED / REFUNDED | Partial/full refund. Check the specific refund transaction; do not record a new payment. | | PAY_CANCELED / CANCELED | Payment 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_ERROR | Keep 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 ```json { "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 \{#best-practices} | Area | Recommendation | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Activation Management | Securely persist caller terminal_sn / terminal_key; manage activation separately from target-device binding. | | Key rotation | Call /terminal/checkin according to the integration configuration and update the key atomically; no universal daily frequency is assumed. | | Order Number Uniqueness | Keep out_trade_no unique within the merchant. Preserve the original ID for the same business operation; query unknown outcomes before another collection. | | Dual Confirmation | Use both notifications and queries; do not overwrite distinct transactions or regress confirmed state with an old event. | | Exception Handling | On network timeout, query order status before retrying. Never blindly resend. | | Reconciliation | Reconcile payments, refunds and statements by merchant, store and business date; /mis/shift does not confirm settlement of funds. | | Logging | Log redacted business IDs, request time, states and error codes. Exclude keys, full card numbers and sensitive payloads. | | Idempotency | Deduplicate notifications by transaction and state. Assign an ID to each new refund; preserve it while its outcome is unknown. | ## Timeouts, Duplicates and Recovery \{#reliability} 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. | Trigger | Immediate Action | Recovery / Stop Condition | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Push timeout, disconnect, 5xx or invalid response signature | Retain 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 acceptance | The 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 state | Keep 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_ERROR | Query 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 payment | Retain 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 notification | Verify 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 outage | Reduce 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.