iOS SDK

Initialize, configure, and launch the Vrtx iOS SDK inside your host application. This guide covers supported iOS versions, installation, setup, host app configuration, callbacks, authentication, session behavior, and troubleshooting.

Overview

The Vrtx SDK provides a native iOS wallet and onboarding experience that can be presented from your host application. Supported flows may include KYC, OTP verification, Nafath authentication, wallet login, and card flows.

The SDK is UIKit-based and presents its own UINavigationController flow from a host UIViewController.

Supported iOS Versions & Requirements

Installation

The SDK is delivered as VRTX.framework or VRTX.xcframework. You can either embed the framework directly or add the SDK project as a subproject.

Option A — Embed Framework

Embed VRTX.framework / VRTX.xcframework

Use this option if you already have the SDK framework package.

1. Add the framework to your project.
2. In your app target, add it under Frameworks, Libraries, and Embedded Content.
3. Set the framework to Embed & Sign.
4. Import the SDK in your host code: import VRTX

Option B — Add Subproject

Add VRTX.xcodeproj as a subproject

Use this option if you are integrating the SDK as an Xcode project.

1. Drag VRTX/VRTX.xcodeproj into your host app project.
2. Add VRTX.framework to your host target’s Frameworks, Libraries, and Embedded Content.
3. Ensure Embed & Sign is enabled.
4. Import the SDK in your host code: import VRTX

Quick Start

Call Vrtx.setup from the host app after you have the required credentials.

import VRTX

Vrtx.setup(
    environment: .sandbox,
    clientID: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    mode: .light,
    language: .english,
    fontFamily: "Inter", // Optional. Omit to use the SDK default font per language.
    onSuccess: {
        // SDK UI launched successfully.
    },
    onError: { error in
        // Handle setup or launch failure.
        // Example: error.status, error.message
    }
)

Contract

Required Host App Configuration

The SDK may use Nafath deep-linking, biometrics, and NFC depending on the enabled flows. Configure the required host app settings before launching the SDK.

Nafath URL Scheme

Nafath deep-linking requires the nafath:// URL scheme to be whitelisted in the host app.

Add the following to Info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>nafath</string>
</array>

Face ID Usage Description

If biometrics are enabled in the SDK, add the Face ID usage description to Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>Use Face ID to quickly and securely access VRTX Pay</string>

If this key is missing, the SDK will display a configuration error when the biometric enable step is reached.

NFC Capability

NFC configuration is required only for physical card flows that use Core NFC.

1. In the host app target, go to Signing & Capabilities.
2. Enable Near Field Communication Tag Reading.
3. Add the NFC usage description to Info.plist:

<key>NFCReaderUsageDescription</key>
<string>Scan your card securely to activate it</string>

4. Add ISO7816 select identifiers to the host app entitlements if the physical card flow requires ISO7816 tags:

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>325041592E5359532E4444463031</string>
    <string>A0000000031010</string>
    <string>A0000000032010</string>
    <string>A0000000032020</string>
    <string>A0000000980840</string>
    <string>A0000000041010</string>
</array>

SDK Callbacks & Lifecycle

The SDK exposes callbacks through Vrtx.setup.

Authentication

The SDK authenticates with the Vrtx backend using a client credentials flow.

The SDK requests /auth/token and injects the returned bearer token into subsequent API requests.

Integration Checklist

Troubleshooting

Nafath app does not open

Check that LSApplicationQueriesSchemes includes nafath:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>nafath</string>
</array>

Face ID configuration error is shown

Add NSFaceIDUsageDescription to the host app Info.plist.

<key>NSFaceIDUsageDescription</key>
<string>Use Face ID to quickly and securely access VRTX Pay</string>

NFC scanning does not start or fails immediately

Confirm the following:

• NFC capability is enabled for the host target.
• NFCReaderUsageDescription exists in Info.plist.
• Required AIDs are present in the host app entitlements under iso7816.select-identifiers.
• The physical card flow is enabled only where NFC is required.

SDK does not launch

Confirm the following:

• Vrtx.setup is called with valid clientID and clientSecret.
• The selected environment is correct.
• The host app handles onError and displays the returned error message where appropriate.
• Required host app configuration is present for the enabled flows.