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.
Build Issues
Runtime Issues
NFC Issues
Transaction Issues
Build Issues
Repository Access Denied (401)
New v1.0.5Gradle 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.
Loading...Step 2a — settings.gradle inside dependencyResolutionManagement
Read credentials from local.properties and pass them to the repository block. Select your project's DSL below:
Loading...Step 2c — Older project structure: root build.gradle
If your project does not use dependencyResolutionManagement(older AGP structure), add the repository to the allprojects block in the root-level build.gradle:
Loading...Step 3 — Verify credentials & re-sync
After saving, run a clean Gradle sync:
Loading...If it still fails, double-check the username/password from your EdfaPay representative and confirm there are no trailing spaces in local.properties.
CI/CD Environments
In CI (GitHub Actions, Bitrise, Jenkins, etc.) set MAVEN_USER and MAVEN_PASS as encrypted environment secrets. The fallback to System.getenv() in the snippets above handles this automatically — no changes needed between local and CI builds.
META-INF Duplicate Files
Build fails with "Duplicate files copied in APK META-INF"
Cause: Multiple dependencies include the same META-INF files.
Solution:
Loading...Incompatible Gradle Version
Build fails with Gradle or AGP compatibility errors
Cause: SDK requires Gradle 8.11.1+ and AGP 8.9.1+.
Solution:
Loading...SDK Version / compileSdk Mismatch
Error: requires libraries to compile against version 36
Cause: The SDK requires a newer compileSdk than your project currently uses.
Solution: Update app/build.gradle.kts:
Loading...ProGuard/R8 Stripping Classes
Release build crashes with ClassNotFoundException
Cause: ProGuard removing SDK classes during minification.
Solution: Add to proguard-rules.pro:
Loading...minSdk Version Too Low
Manifest merger failed: uses-sdk:minSdkVersion
Cause: SDK requires minSdk 29 (Android 10).
Solution:
Loading...Runtime Issues
SDK Initialization Fails
onError callback fires during initiate()
Possible causes:
- Invalid or expired auth token
- No internet connection
- Wrong environment (SANDBOX vs PRODUCTION)
- Terminal not provisioned for this app
Debug Steps
- Enable debug logging:
EdfaPayPlugin.enableLogs = true - Verify credentials with your account manager
- Check network connectivity
- Ensure correct environment setting
FragmentActivity Required
ClassCastException when calling SDK methods
Cause: SDK requires FragmentActivity context, not plain Activity.
Solution:
Loading...Session Expired Errors
Operations fail with session expired message
Cause: Authentication session has expired.
Solution:
Loading...NFC Issues
Card Not Reading Properly
Card tap not being detected or reads fail
Common causes:
- Card held too far from NFC antenna
- Phone case interfering with NFC signal
- Multiple cards in wallet causing collision
- Card chip damaged or demagnetized
Best Practices
- Remove phone case for better NFC reception
- Hold card flat against phone back
- Keep card still for 1-2 seconds
- Test with different cards to isolate issue
Finding NFC Antenna Position
Locate optimal card placement area
NFC antenna position varies by device. Common locations:
Center back (most devices)
Upper back (Samsung)
Near camera (some Pixels)
Transaction Issues
| Issue | Cause | Solution |
|---|---|---|
| Transaction declined | Card issuer declined | Check response code, try different card |
| Timeout during payment | Slow network or server | Increase timeout, check connectivity |
| Duplicate transaction | Same orderId used twice | Generate unique orderId per transaction |
| Refund fails | Original transaction not found | Use correct originalTransactionId |
| Amount mismatch | Wrong amount format | Use cents/minor units (1000 = $10.00) |
| Terminal not active | Terminal deactivated | Call activateTerminal() first |
Debugging Tips
Enable SDK logging to diagnose issues:
Loading...Log Levels
D/- Debug infoI/- Transaction eventsW/- WarningsE/- Errors
Key Log Tags
EdfaPay- General SDKEdfaPay-NFC- Card readingEdfaPay-Network- API callsEdfaPay-EMV- EMV processing
Need More Help?
If you're still experiencing issues, contact our developer support:
- Email: developer-support@edfapay.com
- Include: SDK version, device model, Android version, and logs
On this page
Downloads
Coming SoonSample apps, release bundles, and more content will be available here soon.