Wallet Guide

Wallet SDK supports two integration modes: headless methods and complete built-in UI. Choose one mode per feature or mix both in the same app.

For method signatures and platform code, see the Wallet SDK guide. For returned data, see Wallet models.

Integration modes

Headless methods

Headless methods return wallet data and results without showing SDK screens. Use them when your app owns the interface, navigation, validation, loading states, and error messages.

Headless methods cover:

  • Balance
  • Transaction history
  • Beneficiaries
  • Transfers
  • Top-up
  • Card issue, list, details, and spend

Complete built-in UI

Built-in methods open complete native wallet screens. The SDK handles the interface, validation, loading states, and flow.

Built-in methods cover:

  • showBalance
  • showTransactions
  • showBeneficiary or showBeneficiaries
  • showTransfer
  • showTopUp
  • showCards

Both modes use the same wallet session. You can use built-in UI for one feature and headless methods for another.

Wallet flow

1. Check if the user has a wallet account

  • New user: Call onboarding().
  • Existing user: Continue to session check.

2. Check the existing user's session

  • Call getSession() when the user already has an active session.
  • Call login() when the user needs to authenticate again.

Both methods return a wallet handle after success.

3. Use wallet

Keep the wallet handle in memory. Use built-in UI or headless methods for wallet features.

4. Sign out

Call signOut() when the user wants to leave the wallet.

New users

Call onboarding() for users without a wallet account.

Onboarding handles:

  • Account details
  • Mobile OTP
  • Nafath identity verification
  • Address
  • Terms and conditions

The call returns a wallet handle after onboarding finishes.

Keep the host screen visible. Do not open another modal while onboarding is active.

View onboarding implementation

Existing users

Call login() for users who already have a wallet account.

Login opens native mobile-number and OTP screens. The call returns a wallet handle after successful verification.

Treat user dismissal as cancellation. Do not show a failure message when the user closes the flow.

View login implementation

Returning sessions

Call getSession() during app startup.

A valid session returns a wallet handle without showing UI. When no session exists, show your login or onboarding entry point.

Saved authentication state can expire. Always restore the session before protected wallet actions.

View session implementation

After authentication

Store one wallet handle near your app root. Use it for:

  • Balance
  • Transaction history
  • Beneficiaries
  • Transfers
  • Top-up
  • Cards

Do not persist the wallet handle yourself. The native SDK manages secure session storage.

Built-in screens

Use complete built-in UI when you want the SDK to manage the screen and flow.

  • showBalance
  • showTransactions
  • showBeneficiary or showBeneficiaries
  • showTransfer
  • showTopUp
  • showCards

Present from a visible screen. Wait for existing app modals to close. Never present two wallet screens together.

Headless methods

Use headless methods when your app provides its own interface and user flow.

Available headless flows include:

  • Read balance
  • Load transaction history
  • List, add, verify, and remove beneficiaries
  • Transfer funds
  • Top up wallet
  • Issue, list, view, and spend with cards

Validate input before calling the SDK. Disable action buttons while requests run. Refresh affected data after a successful action.

Sign out

Call signOut() when the user signs out. Clear your app wallet state after the call finishes.

View sign-out implementation