iOS 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

WirexMobileSDK is a Swift framework for UIKit apps, distributed through Swift Package Manager and CocoaPods.
It draws card values in sealed native views: a revealed card number, a card the user is typing and a wallet
payment token stay inside the SDK and never reach your app code. Your 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
WirexCredentialProvider 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 checkout for a top-up your backend priced	Apple Pay Top-Up

Version. These pages document WirexMobileSDK 0.3.15. The same framework backs the
React Native SDK and the Flutter SDK on iOS.

Card Top-Up Flow

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

    App->>SDK: 1. collect.form(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	`WirexCollectForm`	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 iOS SDK
    participant BaaS as Wirex BaaS

    User->>App: 1. Request card details
    App->>SDK: 2. reveal.session (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	`session(cardId:fields:cardholderName:)`	One session per open details view
3–4	`actionToken(scope:)`	Your provider mints a `GetCardDetails` action token
5	SDK to Wirex	Responses are drawn in sealed rows; your code never sees them
6	`onChange`	`idle`, `loading`, `ready` or `error`, with per-field outcomes

Apple Pay Top-Up Flow

sequenceDiagram
    participant User as Cardholder
    participant App as Your App
    participant SDK as iOS 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)
    Backend->>BaaS: 2. POST /api/v1/cards/topup/token
    App->>SDK: 3. WirexWalletCheckoutView (quote, providerConfig, auth)
    User->>SDK: 4. confirm in the Apple 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`; 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 Apple Pay 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, sizing
Collect a Card	Top-up and payout card entry, single rows, tokenize results
3DS Challenge	Running the issuer challenge and telling the endings apart
Apple Pay Top-Up	Checkout view, token and legacy modes, re-arming
Appearance and Strings	`WirexAppearance`, icons, copy and sizing for every surface
Errors, Logging and Troubleshooting	`WirexError` codes and reasons, logging, timeouts, common failures

SDK Setup has a complete, end-to-end example. Every public type and member is documented in the framework and appears in Xcode Quick Help.