Errors, Logging and Troubleshooting

Before You Start

Read the following guides before proceeding:

Guide	Why
React Native SDK	Surfaces, isolation model and flows
SDK Setup	Configure options and the credential provider

Where Errors Arrive

Surface	Delivery	Shape
Reveal	In the snapshot — `load()` never rejects for a request failure	`snapshot.error` or `snapshot.fields[i].error`: `{ code, retryable }`
Collect	`tokenizeTopUp()` / `tokenizeOctDestination()` reject	`{ code, retryable, reason? }`; `reason` is `'cardAlreadyLinked'` or `'cardLimitReached'`
3-D Secure	In the outcome	`outcome.error.code`: `'originRefused'`, `'declined'`, `'unavailable'`
Wallet	`executeFailed` and `failed` events	`event.error.reason`, `event.error.kind`

import {
  WirexDeclined, WirexWalletEnvironmentUnavailable, type WirexRevealSnapshot,
} from '@wirexapp/mobile-sdk';

export const revealError = (s: WirexRevealSnapshot) =>
  s.error ?? s.fields.find((f) => f.outcome === 'failed')?.error;
export const isDecline = (e: unknown) => e instanceof WirexDeclined;
export const envReason = (e: unknown) =>
  e instanceof WirexWalletEnvironmentUnavailable ? e.reason : null;

WirexDeclined is the one shared error class: the user said no and nothing was sent. It is not a
failure.
WirexWalletEnvironmentUnavailable is thrown for an unknown wallet environment. reason is
'unknownName', 'notBuilt' or 'malformedEndpoints'. Show the reason; never fall back to another
environment.

Logging

Logging is off by default. Every logged value passes a redactor.

Surface	Option	Values
Reveal, Collect, 3-D Secure	`logging` in `configure(...)`	`'debug'`, `'info'`, `'warn'`, `'error'`. Written to the iOS unified log and Android logcat tag `wirex`
Wallet	`WirexWalletConfig.logging`	`{ level, sink }`. Without a sink nothing is written. Presets: `WirexWalletLogging.disabled`, `WirexWalletLogging.console(level)`

import { WirexWalletLogging, type WirexWalletConfig } from '@wirexapp/mobile-sdk';

export const revealConfigExtras = { logging: 'info' as const, timeouts: { requestSeconds: 15, resourceSeconds: 30 } };
export const walletConfig: WirexWalletConfig = { environment: 'test', logging: WirexWalletLogging.console('info') };

Log at debug in development builds and warn in release.

Timeouts

Values are in seconds.

Surface	Option
Reveal, Collect	`timeouts: { requestSeconds, resourceSeconds }` in `configure(...)`
3-D Secure	`requestSeconds`, `resourceSeconds` top-level in `WirexThreeDS.configure(...)`

Troubleshooting

Symptom	Cause	Resolution
The native module is missing	Expo Go, or the old architecture	Build a development build with the New Architecture enabled
`configure` rejects with an environment error	The build has no endpoints for that environment, or `chainId` is empty	Pass `testMode` / `environment` correctly and a non-empty `chainId`
Reveal or Collect fails with `unauthorized`	Stale bearer. The SDK never retries a `401`	Check expiry and refresh inside `getAccessToken`
API answers `400` on every call	Both `userEmail` and `userWallet` are set	Return exactly one identity
A revealed field is blank	iOS Simulator secure layer, or a row height smaller than `onNaturalHeight`	Test on a device; apply the reported height
Collect cannot tokenize	Billing details missing, or the user is not enrolled at the acquirer	Send every required billing field — see Collect a Card
The Pay button is unavailable	Probe not mounted, empty provider block, or iOS Simulator	Mount `WirexWalletAvailabilityProbe` with the real block; test on a device
Google Pay unavailable on Android 11+	Missing `<queries>` intents	Add the Expo plugin or the intents — see SDK Setup
3-D Secure ends in `pending`	The payment is not settled yet	Not an error. Settle from the top-up status