Troubleshooting Passkey & Biometric Authentication

Amwal utilizes FIDO2 / WebAuthn standard passkeys to enable frictionless 1-tap checkout with Apple FaceID, TouchID, and Android Biometrics. When a customer encounters issues authenticating via biometrics, follow this guide.

Common Passkey Failure Modes

1. In-App WebViews Without WebAuthn Support

• Symptom: Clicking "Pay with Passkey" does not trigger the native FaceID / TouchID system sheet.
• Root Cause: In-app browsers (e.g., embedded WebViews inside Instagram, TikTok, or legacy mobile app wrappers) may restrict WebAuthn APIs for security sandboxing.
• Resolution:
  • Amwal automatically detects WebView limitations and smoothly falls back to a 4-digit SMS OTP sent to the customer's verified Saudi mobile number (+9665xxxxxxxx).
  • For mobile app developers, ensure your WebView enables setWebContentsDebuggingEnabled(true) or uses standard Chrome Custom Tabs (Android) / ASWebAuthenticationSession (iOS).

2. Private Browsing / Incognito Mode

• Symptom: Browser prompts for new device registration on every visit.
• Root Cause: Safari and Chrome in Incognito mode disable persistent passkey credential storage.
• Resolution:
  • The customer can complete authentication via the instant SMS OTP verification screen.

3. Customer Changed Phone Number or Lost Device

• Symptom: Passkey credentials cannot be found for the customer account.
• Resolution:
  • The customer selects "Verify with SMS".
  • Once verified, Amwal re-enrolls the new device passkey seamlessly with the customer's consent.

Verifying Browser Compatibility

Amwal Passkey authentication is supported natively on:

• iOS / macOS: Safari 14+, Chrome 108+, Edge 108+ (FaceID / TouchID / Apple Keychain)
• Android: Chrome 108+, Samsung Internet 19+ (Fingerprint / Face Unlock / Google Password Manager)
• Windows: Windows Hello (PIN, Fingerprint, Facial Recognition) on Chrome & Edge