> 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.