Troubleshooting
Common issues and solutions when integrating the EdfaPay Soft POS.
Overview
This guide covers common integration issues organized by category. For each issue, we provide the symptoms, cause, and solution.
5
Build Issues
3
Runtime Issues
3
NFC Issues
4
Transaction Issues
Build Issues
Repository Access Denied (401)
Gradle sync fails with "401 Unauthorized" accessing the EdfaPay Maven repository. Cause: The EdfaPay Maven repository requires authenticated access. Gradle cannot download the SDK artifact because credentials are missing, incorrect, or placed in the wrong file. Step 1 — Store credentials in local.properties: Add your credentials to local.properties in your project root. Never commit this file. Make sure it is in .gitignore. Step 2 — Reference credentials in settings.gradle inside dependencyResolutionManagement.
Loading...META-INF Duplicate Files
Build error: "2 files found with path 'META-INF/DEPENDENCIES'" Cause: Multiple libraries bundle identical META-INF files, and Gradle's default behavior is to fail on duplicates. Solution: Add packaging exclusions to your app-level build.gradle.kts:
Loading...Incompatible Gradle Version
Build failure with Gradle compatibility errors. Solution: Use Gradle 8.4+ with AGP 8.9.1+:
Loading...SDK Version / compileSdk Mismatch
Build warning or error about target SDK version mismatch. Solution: Use compileSdk 36 with minSdk 29:
Loading...ProGuard/R8 Stripping Classes
Runtime crashes after enabling ProGuard/R8 in release builds. Solution: Add EdfaPay keep rules to your proguard-rules.pro:
Loading...minSdk Version Too Low
Build error: "uses-sdk:minSdkVersion X cannot be smaller than version 29" Solution: Set minSdk to 29 (Android 10) in your app-level build.gradle.kts:
Loading...Runtime Issues
SDK Initialization Fails
EdfaPayPlugin.initiate() calls onError callback immediately. Common causes: • Invalid or expired auth token • No internet connectivity at initialization time • Server unreachable (check Env.SANDBOX vs Env.PRODUCTION) Solution: Verify credentials, check network connectivity, and ensure correct environment is selected.
FragmentActivity Required
RuntimeException: "SDK requires FragmentActivity or AppCompatActivity" Solution: Your Activity must extend AppCompatActivity (or FragmentActivity):
Loading...Session Expired Errors
EdfaError with code in 3xxx range after SDK was previously working. Cause: SDK sessions expire after a period of inactivity or when the server invalidates them. Solution: Re-initialize the SDK when session expires:
Loading...NFC Issues
Card Not Reading Properly
Card tap detected but reading fails or times out. Common causes: • Card removed too quickly (less than 2 seconds) • Card not positioned over NFC antenna • Interference from phone case or other cards • Damaged NFC chip on card Solution: Guide user to hold card flat for at least 2 seconds at the NFC antenna location.
Finding NFC Antenna Position
NFC antenna position varies by device model. Generally: • Most Android devices: center or upper-back area • Samsung: back center • Google Pixel: back center/upper • Xiaomi/OPPO/Vivo: back center Tip: Use an NFC-enabled app to locate the exact antenna position on a specific device model.
Transaction Issues
Transaction Always Declined
All transactions return decline response. Common causes: • Testing with a sandbox environment but using production card credentials • Terminal not properly configured on EdfaPay server • Missing required TXN parameters Solution: Verify you are using the correct environment (Env.SANDBOX for testing) and use test cards provided by EdfaPay.
onPaymentProcessComplete Not Firing
Payment appears to complete but callback is never called. Cause: The callback can fire up to 3 times with FlowType.DETAIL. Always check isFlowComplete flag before processing results. Solution: Gate your logic on isFlowComplete === true.
Duplicate Transaction Prevention
Concern about duplicate charges if app crashes mid-transaction. Solution: Use the transaction RRN (Reference Retrieval Number) returned in onPaymentProcessComplete to check for existing transactions before initiating a new one. The SDK does not automatically prevent duplicates at the application level.
Void / Reversal Not Working
Void or Reversal returns error response. Note: Void is only available for same-day transactions that have not yet been settled. Reversal is a technical operation for failed or timed-out transactions. Solution: Ensure the original transaction's approval code and RRN are passed correctly and the transaction is within the allowed time window.
Debugging Tips
Enable verbose logging to diagnose issues quickly.
Loading...Production Builds
Always disable verbose logging (enableLogs = false) in production builds to avoid exposing sensitive transaction data in device logs.
On this page
Downloads
Coming SoonSample apps, release bundles, and more content will be available here soon.