> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Testing & Troubleshooting ## Errors and Troubleshooting \{#errors} Inspect top-level `result_code/error_code`, then `biz_response.result_code/error_code/error_code_standard`. These are common verified defaults; deployment mappings can change messages and standard codes. Do not branch on human-readable text. | Code / Symptom | Meaning and Action | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ILLEGAL_SIGN | Match terminal_sn in header/body; check credential scope, lowercase algorithm, final raw body and key rotation. Run the signature vector first; never share keys with support. | | INVALID_PARAM | Check types, lengths, positive integer amounts and required fields; establish whether the original operation could have been accepted before resubmission. | | PRE_AUTH_PAY_TYPE_MIX_ERROR | Unsupported combination of preauthorization and other payment types; use the enabled device capability. | | PUSH_DEVICE_SN_ERROR / TERMINAL_SN_UN_BIND | Unknown device or unbound caller terminal; check TUSN, credentials and binding. | | STORE_NOT_MARCH / MERCHANT_NOT_MARCH | Store/merchant relation is invalid. MARCH is the actual API spelling. Fix binding without bypassing authorization. | | DEVICE_TYPE_NOT_SUPPORT | Unsupported route/device; check firmware and application enablement. | | DEVICE_OFFLINE / DEVICE_STATUS_UN_KNOW | Offline/unknown status on routes that check it. Restore connectivity and device login, then query the original order. Not all routes expose these errors. | | PUSH_FAIL / MIS_PUSH_FAIL / ERROR / UNKNOWN_SYSTEM_ERROR | Recover as an uncertain outcome: retain IDs, query and collect evidence. FAIL alone is not permission to collect again. | | ORDER_CLOSE_ABORT_IN_PROGRESS | Close pending, even when result_code is MIS_PUSH_SUCCESS; keep querying. | | ORDER_CLOSE_ERROR / UPAY_QUERY_ORDER_ERROR | Close/query error; check the payment and escalate persistent uncertainty. | | PAY_TYPE_CANCEL_NOT_SUPPORTED | Current cancellation is unsupported. Follow device/channel rules and query; this does not confirm a refund. | | REFUND_IN_PROGRESS / REFUND_ERROR | Refund business result codes; query with the original refund ID. | | ILLEGAL_REQUEST or HTTP 429/rate-limit response | Potential ingress limit; reduce query frequency/concurrency. Confirm assigned limits and reconcile any money-moving operation. | ### Support Diagnostic Package - **Environment and devices:** environment, merchant/store IDs, caller `terminal_sn` and target device. - **Orders and transactions:** `out_trade_no` / `client_sn`, `sn`, `tsn` and refund ID. - **Request and response:** time with timezone, API path, HTTP status, both result-code layers and any returned trace identifier. - **Investigation:** queries attempted and device symptoms. Share redacted samples only; exclude keys, full card numbers and sensitive personal data. Use the technical-support channel provided during onboarding and keep the operation pending reconciliation. ## Integration Tests and Launch \{#testing} Run these cases in an authorized test environment and retain redacted evidence. Documentation verification does not mean they passed on actual devices/channels; arrange controlled integration tests where no simulator exists. | Scenario / Trigger | Required Behavior | Evidence | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | | Successful payment: push and pay on device | Wait after acceptance; confirm by query/verified event; fulfill once. | Matching out_trade_no/sn, amount and PAYMENT transaction. | | Timeout: test proxy drops accepted response | No new order ID; recover by client_sn. | Original order recovered without duplicate collection. | | Unpaid/offline: disconnect test device | Do not infer a financial result from push failure or no order; query after recovery. | Explainable device, push and query records. | | Concurrent/duplicate submission | Locally limit duplicates, retain original IDs and reconcile. | One expected funds movement, without assuming response replay. | | Signature: tamper with body/signature/key | Reject invalid events; accept authentic samples. | Correct raw-byte verification including Chinese text, whitespace and escaping. | | Notification retry: HTTP 500 or quoted success | Retry occurs; exact plain-text success stops retries. | HTTP status, exact response bytes and delivery timing. | | Duplicate/out-of-order: replay valid snapshots in a local stub | Apply each effect once; old payment cannot overwrite refund. | Idempotency records agree with final query. | | Partial/repeated refunds: enabled capabilities only | Record and query each refund ID; preserve IDs on unknown outcomes. | Refund totals, net_amount and order match, without over-refund. | | Lost refund response | Recover using original refund ID; no alternate-route resubmission. | One confirmed refund transaction. | | Payment/close race | Reconcile ORDER_CLOSE_ABORT_IN_PROGRESS; no premature cancellation. | Payment/reversal and local records agree. | | Check-in: key rotation across instances | Verify success with new key; subsequent requests work without stale overwrites. | Redacted verification/version records; no exposed keys. | | Cross-day reconciliation and shift | Distinguish transaction completion, device shift and fund settlement. | Statements match IDs and the confirmed timezone/cutoff. | ### Before Launch - Production merchant/store, target device and caller binding are consistent; currency and payment methods are enabled. - Test/production endpoints, keys and callback domains are separated; secure key storage and valid TLS are in place. - Payment, refund, notification, timeout and duplicate-operation tests have evidence; unknown outcomes have a human recovery path. - Confirm rate limits, firmware, refund limits/permissions/fees, cancellation callbacks and reconciliation/settlement rules. - Set monitoring and support ownership; complete the agreed small-value production validation before scaling up. See [Sources and Open Items](/guide/sources.md#sources) for capability owners, required evidence and the original code verification scope.