Troubleshooting and Support Evidence

This page maps common failures to the checks you should run first and the evidence AppInChina needs to help efficiently. The goal is a path that is neither dismissive nor open-ended.

Do not classify a failure as a wallet defect before checking whether an AppInChina order exists and reviewing the relevant client-side evidence. A payment attempt that never created an order is, by default, a client-side preflight matter until the evidence identifies the cause.

Related docs

• Preflight and stages: Client Payment Preflight and Acceptance Testing
• Backend verification: Server Verification and Entitlements
• Android components: Payments SDK Integration Guide for Android
• Endpoint contract: Payments API Reference
• Server error codes: Error Reference

Failure classification

Use the observed state to classify the problem, run the client-side checks first, and — only if unresolved — send the listed evidence.

Observed state	Initial classification	Client checks first	What to send AppInChina if unresolved
Wallet cannot be installed, registered, verified, or linked to a card	Wallet / card readiness	Wallet prompts; country/phone/ID/card eligibility; card issuer response.	Wallet name/version; redacted screenshots; country; card brand/issuer only if the tester is comfortable sharing; exact error and time.
Payment attempt does not create an AppInChina order	Client-side preflight	Wallet readiness; SDK invocation parameters; app logs; build/version; callback/result configuration.	APK/AAB build ID; device/OS; payment method; timestamp and time zone; sanitized logs around the attempt; screenshots; user/bizNo if generated.
Order exists but is not paid	Transaction state investigation	Order status; displayed wallet outcome; retry/duplicate behavior; network/app logs.	Order/bizNo; method; timestamp; sanitized logs; exact UI state; confirmation that the app build matches the test build.
Order is paid but app reports failure or does not return correctly	Client post-payment handling	Result Activity/callback implementation; release merged manifest; crash/error logs; app navigation.	Order/bizNo; APK build; exact stack/log excerpt; manifest / result-Activity verification; screen capture only if needed.
Order is paid, but entitlement/access is missing	Client backend / entitlement	Backend verification response; idempotency logic; user-to-customerIdentity mapping; entitlement update and app refresh.	Order/bizNo; sanitized verification records; entitlement audit trail; current client account state; timestamps.
Access was granted but history/refund state is wrong	Client history / reconciliation	Canonical history call/method; pagination; latest verified status; refund reconciliation job.	Request/response redacted of secrets; endpoint/method; user/bizNo; expected vs actual record; timestamps.

Understanding SDK error 99999

99999 means the Android SDK caught an unexpected local exception while processing the request or payment flow. It can result from a missing Activity, a dependency/configuration problem, a JSON parsing error, or another unhandled runtime failure.

99999 is not a payment decline

99999 is not enough to identify the cause and does not, by itself, show that AppInChina's backend or a payment provider rejected the transaction. Obtain the underlying Android exception and surrounding logs, then classify the failure.

Evidence to collect for 99999:

• Exact timestamp and time zone.
• Application ID, app version, version code, and whether the build is debug or release.
• Device brand/model, Android version, and wallet-app version where relevant.
• The complete exception and surrounding Android log — not only the error code.
• Whether an AppInChina order was created, plus bizNo if available.
• Which wallet/channel was selected.
• Gradle dependency report for FastJSON/FastJSON2 if the exception concerns class loading, JSON parsing, or a compatibility change (see FastJSON dependency issues).
• Final merged manifest for Activity/callback errors.

Triage rule:

• If an order was created or paid, investigate the post-payment callback, verification, and entitlement path in parallel with any client crash.
• If no order reached AppInChina, first inspect the local exception, SDK setup, wallet readiness, and request parameters. Do not label it a backend payment failure without supporting evidence.

WeChat-specific failures

Symptom	First checks	Evidence for support
WeChat option appears but no wallet handoff occurs	Confirm initPayTools() succeeded in the same process before startPayment(); confirm WeChat is installed and the configured channel is returned.	Timestamp; SDK log; initPayTools() result/error; app version/build; device/Android version.
Wallet completes but app does not refresh access	Confirm WXPayEntryActivity is correctly packaged and declared; trace its route to backend verification and entitlement refresh.	Callback logs; merged manifest; order bizNo; backend verification record; current entitlement response.

See the WeChat payment lifecycle for the full init → callback → verification path.

FastJSON dependency issues

The SDK requires legacy FastJSON 1.x (com.alibaba:fastjson), which is a different dependency family from FastJSON2 (com.alibaba.fastjson2:fastjson2). See Prerequisites §3.2.

Situation	What to do
ClassNotFoundException, NoClassDefFoundError, or a crash identifying com.alibaba.fastjson	Confirm the approved FastJSON 1.x dependency is declared and resolved into the release build. Provide the full exception and dependencyInsight output.
Another library resolves a different FastJSON 1.x version	Resolve to one Engineering-approved FastJSON 1.x version for that module family; retest the release artifact. Do not pick a version solely because it is newer.
The app also includes FastJSON2	Keep FastJSON2 versioning explicit and test the whole app. Do not describe it as a replacement for FastJSON 1.x.
Device/Android-specific JSON crash	Capture device/OS, app build, SDK artifact version, full exception, and both FastJSON/FastJSON2 resolved versions before escalating.

Privacy rule

Never request sensitive data

Never ask a client — and never send AppInChina — passwords, card numbers, wallet authentication codes, full device dumps, access tokens, or production secrets. Request an excerpt of a sanitized log covering the attempt, not an unbounded full log, unless Engineering specifically needs it under a secure process.

Example of a sanitized log excerpt

Send the window around the attempt with secrets removed:

2026-08-03 14:30:01.220 +0800  ACP/pay  startPayment channel=WECHAT bizNo=ORDER_20260803_0001 customerIdentity=user_12345
2026-08-03 14:30:02.880 +0800  ACP/pay  wallet launched
2026-08-03 14:30:19.104 +0800  ACP/pay  return-to-app; querySingleOrder bizNo=ORDER_20260803_0001
2026-08-03 14:30:19.550 +0800  ACP/pay  paymentStatus=PAID pmtDt=1754203818000
2026-08-03 14:30:19.560 +0800  APP/entitlement  grant productId=pro_3m result=OK

Redact APP_SECRET, tokens, phone numbers, and card data before sharing. Include the timestamp and time zone so the attempt can be correlated with the backend order record.