Android Mobile SDK FAQs

1. Which method should I use to start the checkout flow?

Use initializeSDK on ExpressSDKInitializer.

2. What should I do when the onSuccess callback is received?

Show a "processing" experience immediately, then verify the order on your backend or using the Transaction Status API. Only mark the order as completed after successful verification.

3. What is the difference between onError and onCancel callbacks?

onError indicates a technical or business failure.

onCancel indicates that the user or payment flow was cancelled.

Treat both outcomes as non-successful transactions, but use different retry flows and user messaging strategies.

4. Why am I getting token-related errors?

The initializer returns invalid token errors for null, empty, or invalid contexts.

Also verify:

Token generation timing
Token expiry windows
Correct environment token usage

Make sure you are using the correct environment token.

5. Can I retry a payment using the same token?

Best practice is no. Generate a fresh backend token for each payment attempt to avoid duplicate, expired, or conflicting order states.

6. How should I use sandbox mode?

Enable sandbox mode only for QA and UAT testing. Keep production builds hard-wired to production configuration and validate this as part of your release checklist.

7. What information should I store for troubleshooting and support?

Store the following information:

orderId
Your attemptId
Callback type
SDK code and message
Timestamp
Backend verification result
Traces and logs from Logcat

Avoid storing sensitive payloads.

8. How do I resolve a Gradle sync error?

Please invalidate cache and restart, and make sure you are using the latest version of the SDK.

Merchant action:

In Android Studio, go to File > Invalidate Caches / Restart
Re-sync Gradle
Ensure the correct JDK and Gradle wrapper versions are configured for the project
If the issue persists, delete the local .gradle cache and sync again

9. Why am I getting an SDK start error related to device or network checks?

If the SDK throws an error while starting, make sure:

The device is not rooted
The internet connection is stable
The SDK can access the internet when using VPNs, proxies, or specific network protocols

Merchant action:

Verify that the device is not rooted (the SDK blocks rooted devices)
Check active internet connectivity and any firewall, proxy, or VPN restrictions
Confirm that the app has internet permission and that network security settings allow access to SDK endpoints
Retry SDK initialization using a fresh token, if applicable

10. What should I do if the transaction fails?

Transaction Failed – Transaction failed due to an API error, timeout, or session expiry.

Merchant action:

Do not mark the order as paid based solely on the client callback
Re-verify the payment status using your backend or reconciliation API
If the session has expired, generate a fresh token or session and retry

11. What should I do if the transaction is cancelled?

Transaction Cancelled – The end user cancelled the transaction.

Merchant action:

Mark the payment attempt as cancelled (not failed) in analytics
Keep the cart or order recoverable and allow a quick retry
Avoid creating duplicate orders during repeated payment attempts