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/testing.md.
  • English
  • Testing & Troubleshooting

    Errors and Troubleshooting

    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 / SymptomMeaning and Action
    ILLEGAL_SIGNMatch 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_PARAMCheck types, lengths, positive integer amounts and required fields; establish whether the original operation could have been accepted before resubmission.
    PRE_AUTH_PAY_TYPE_MIX_ERRORUnsupported combination of preauthorization and other payment types; use the enabled device capability.
    PUSH_DEVICE_SN_ERROR / TERMINAL_SN_UN_BINDUnknown device or unbound caller terminal; check TUSN, credentials and binding.
    STORE_NOT_MARCH / MERCHANT_NOT_MARCHStore/merchant relation is invalid. MARCH is the actual API spelling. Fix binding without bypassing authorization.
    DEVICE_TYPE_NOT_SUPPORTUnsupported route/device; check firmware and application enablement.
    DEVICE_OFFLINE / DEVICE_STATUS_UN_KNOWOffline/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_ERRORRecover as an uncertain outcome: retain IDs, query and collect evidence. FAIL alone is not permission to collect again.
    ORDER_CLOSE_ABORT_IN_PROGRESSClose pending, even when result_code is MIS_PUSH_SUCCESS; keep querying.
    ORDER_CLOSE_ERROR / UPAY_QUERY_ORDER_ERRORClose/query error; check the payment and escalate persistent uncertainty.
    PAY_TYPE_CANCEL_NOT_SUPPORTEDCurrent cancellation is unsupported. Follow device/channel rules and query; this does not confirm a refund.
    REFUND_IN_PROGRESS / REFUND_ERRORRefund business result codes; query with the original refund ID.
    ILLEGAL_REQUEST or HTTP 429/rate-limit responsePotential 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

    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 / TriggerRequired BehaviorEvidence
    Successful payment: push and pay on deviceWait after acceptance; confirm by query/verified event; fulfill once.Matching out_trade_no/sn, amount and PAYMENT transaction.
    Timeout: test proxy drops accepted responseNo new order ID; recover by client_sn.Original order recovered without duplicate collection.
    Unpaid/offline: disconnect test deviceDo not infer a financial result from push failure or no order; query after recovery.Explainable device, push and query records.
    Concurrent/duplicate submissionLocally limit duplicates, retain original IDs and reconcile.One expected funds movement, without assuming response replay.
    Signature: tamper with body/signature/keyReject invalid events; accept authentic samples.Correct raw-byte verification including Chinese text, whitespace and escaping.
    Notification retry: HTTP 500 or quoted successRetry 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 stubApply each effect once; old payment cannot overwrite refund.Idempotency records agree with final query.
    Partial/repeated refunds: enabled capabilities onlyRecord and query each refund ID; preserve IDs on unknown outcomes.Refund totals, net_amount and order match, without over-refund.
    Lost refund responseRecover using original refund ID; no alternate-route resubmission.One confirmed refund transaction.
    Payment/close raceReconcile ORDER_CLOSE_ABORT_IN_PROGRESS; no premature cancellation.Payment/reversal and local records agree.
    Check-in: key rotation across instancesVerify success with new key; subsequent requests work without stale overwrites.Redacted verification/version records; no exposed keys.
    Cross-day reconciliation and shiftDistinguish 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 for capability owners, required evidence and the original code verification scope.