React Native SDK

Before You Start

Read the following guides before proceeding:

Guide	Why
PCI Compliant SDK	What the SDK family covers and which platforms it ships for
Authentication	How to mint the user token the SDK authenticates with — see User Token Issuance (Login as User)
Card Top-Up	The estimate and execute calls your backend makes around Collect, 3DS and Wallet
Card Details	The confirmation flow that produces the action token Reveal asks for

Overview

@wirexapp/mobile-sdk is one npm package for React Native apps. It renders card values in native views on
iOS and Android: a revealed card number, a card the user is typing and a wallet payment token stay on the
native side and never cross the JavaScript bridge. Your JavaScript receives tokens, states and events only.

The SDK never mints a credential, never stores one and never moves money on its own. Your app supplies a
credential provider the SDK calls on demand; your backend prices and executes every top-up through the
retail API and passes the results in.

Surface	Credentials	What it does	Guide
Reveal	Yes	Shows the cardholder their own PAN, expiry, CVV and PIN in sealed native rows	Reveal Card Details
Collect	Yes	Captures an external card in a sealed native form and returns a card token	Collect a Card
3-D Secure	No	Renders the issuer challenge returned by a top-up and reports the outcome	3DS Challenge
Wallet	Yes	Embeds the Wirex-hosted Apple Pay / Google Pay checkout for a top-up your backend priced	Apple Pay and Google Pay Top-Up

Version. These pages document @wirexapp/mobile-sdk 0.3.15. The package installs the native SDKs
at its own version: the WirexMobileSDK pod on iOS and com.wirexapp.baas:mobile-sdk on Android.

Not the Web SDK. The browser packages under Web SDK use Wirex-served
iframes and a clientId registered against your origins. The React Native SDK uses native views, takes
chainId instead, and has no CSP or origin registration.

Card Top-Up Flow

sequenceDiagram
    participant User as Cardholder
    participant App as Your App
    participant SDK as Mobile SDK
    participant Backend as Your Backend
    participant BaaS as Wirex BaaS

    App->>SDK: 1. render WirexCollectFormView (profile topup)
    User->>SDK: 2. type PAN / expiry / CVV / name
    SDK-->>App: 3. onChange (isComplete, brand)
    App->>SDK: 4. tokenizeTopUp (billing details)
    SDK->>BaaS: 5. register card
    SDK-->>App: 6. cardId, brand, bin, last4
    App->>Backend: 7. cardId
    Backend->>BaaS: 8. POST /api/v1/cards/topup/estimate
    Backend->>BaaS: 9. POST /api/v1/cards/topup/execute
    BaaS-->>Backend: three_ds_state.url
    App->>SDK: 10. WirexThreeDS session on the URL
    SDK-->>App: 11. outcome (completed / pending / failed / unknown)

Step	Action	Description
1–3	`WirexCollectFormView`	Native card form. `onChange` carries completeness and brand, never values
4–6	`tokenizeTopUp`	Returns `cardId`, the only value to store
7–9	Top-up estimate and execute	Pass `cardId` as `external_card_id` — see Top-Up Transfer
10–11	`WirexThreeDS`	Runs the challenge on `three_ds_state.url`; reconcile the result from the top-up status

Reveal Flow

sequenceDiagram
    participant User as Cardholder
    participant App as Your App
    participant SDK as Mobile SDK
    participant BaaS as Wirex BaaS

    User->>App: 1. Request card details
    App->>SDK: 2. WirexReveal.createSession (cardId, fields)
    SDK->>App: 3. getActionToken(scope)
    App->>BaaS: 4. POST /api/v1/confirmation/signature/verify
    BaaS-->>App: action_token
    App-->>SDK: action_token
    SDK->>BaaS: 5. POST /api/v1/cards/{cardId}/details, /cvv, /pin
    SDK-->>App: 6. snapshot state ready

Step	Action	Description
1–2	`createSession`	One session per open details view
3–4	`getActionToken`	Your provider mints a `GetCardDetails` action token
5	SDK to Wirex	Responses are drawn in native rows; JavaScript never sees them
6	`onSnapshot`	`idle`, `loading`, `ready` or `error`, with per-field outcomes

Wallet Top-Up Flow

sequenceDiagram
    participant User as Cardholder
    participant App as Your App
    participant SDK as Mobile SDK
    participant Backend as Your Backend
    participant BaaS as Wirex BaaS

    App->>Backend: 1. price a top-up
    Backend->>BaaS: POST /api/v1/cards/topup/estimate (apple_pay / google_pay)
    Backend->>BaaS: 2. POST /api/v1/cards/topup/token
    App->>SDK: 3. WirexWalletCheckoutView (quote, providerConfig, auth)
    User->>SDK: 4. confirm in the Pay sheet
    SDK->>BaaS: 5. execute the top-up
    SDK-->>App: 6. executed (id, status)

Step	Action	Description
1	`POST /api/v1/cards/topup/estimate`	`payment_method` is `apple_pay` or `google_pay`; returns `estimation_id`
2	`POST /api/v1/cards/topup/token`	Token mode only — a short-lived token accepted only by estimate and execute
3	`WirexWalletCheckoutView`	Renders the quote and the wallet button
4–6	Pay sheet and execute	Token mode executes inside the checkout; legacy mode emits a wallet token your backend executes with

Guides

Guide	Description
SDK Setup	Requirements, install, Expo, environments, credential provider
Reveal Card Details	Sessions, field rows, masking, sizing
Collect a Card	Top-up and payout card entry, headless layouts, tokenize results
3DS Challenge	Running the issuer challenge and telling the endings apart
Apple Pay and Google Pay Top-Up	Checkout view, token and legacy modes, Custom Tab launch
Appearance and Strings	Theme tokens, icons, copy and sizing for every surface
Errors, Logging and Troubleshooting	Error shapes per surface, logging, timeouts, common failures

SDK Setup has a complete, end-to-end example. Every exported type and member is documented in the package's TypeScript declarations, which editors show inline.