Flutter 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

wirex_mobile_sdk is one pub.dev package for Flutter apps. It renders card values in native platform 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 into Dart. Your Dart code 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 wirex_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.

Same native SDK as React Native. The React Native SDK wraps the same
native SDKs with the same surfaces, environments and credential model. Only the Dart API differs.

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. 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.instance.createSession (cardId, fields)
    SDK->>App: 3. actionToken(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	`actionToken`	Your provider mints a `GetCardDetails` action token
5	SDK to Wirex	Responses are drawn in native rows; Dart 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. WirexWalletCheckoutExecuted (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, environments, credential provider
Reveal Card Details	Sessions, field rows, masking
Collect a Card	Top-up and payout card entry, custom 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, re-arming, Custom Tab launch
Appearance and Strings	Theme tokens, icons, copy and sizing for every surface
Errors, Logging and Troubleshooting	Error types per surface, logging, timeouts, common failures

SDK Setup has a complete, end-to-end example. Every public type and member is documented in the package's API reference on pub.dev.