Payment UI

Learn how to integrate Xplor Pay Payment UI for iOS to accept card-present payments with the VP3300 Bluetooth reader, manual card entry, offline mode, and built-in payment screens.

Payment UI gives your iOS app a ready-made checkout for card-present payments. It wraps the Mobile EMV SDK and handles reader pairing, card collection, validation, and in-app payment screens.

Use it when you want a production-ready payment experience without building your own checkout UI.

At a glance

• Platform: iOS
• Reader support: ID TECH VP3300 over Bluetooth
• Payment flows: Reader-based payments and manual card entry
• Result: A JWT that your app submits as the mobilejwt header

When to use Payment UI

Use Payment UI when you want:

• Built-in payment screens
• Faster iOS integration
• Less UI work for pairing, checkout, and settings

See Mobile EMV SDK directly when you need full control over the payment UI and flow.

Requirements

Before you present Payment UI, make sure you have:

• An iOS app with the Mobile EMV SDK installed
• An ID TECH VP3300 reader for card-present transactions
• Bluetooth enabled on the device
• iOS 14.0 or later for manual card entry
• A payment API integration that accepts mobilejwt

For framework requirements, see Mobile EMV SDK. For a guided build, see iOS Framework quick start.

What Payment UI handles

Payment UI handles the in-app payment experience, including:

• Reader pairing and connection guidance
• Card collection and manual entry forms
• Payment status, validation, and error messaging
• Signature capture, e-mail receipts, and settings
• Offline storage and upload when offline mode is enabled

What your app still handles

Your app still needs to:

• Initialize the SDK
• Present the Payment UI screens
• Submit the JWT to the payment API
• Show the final result in your own app flow

Payment UI handles card interaction and tokenization. Your app handles authorization, capture, and post-payment screens.

Payment UI process flow

1

Initialize the Mobile EMV SDK

Initialize the Mobile EMV SDK before presenting any Payment UI screen.

Make sure your app includes the required frameworks, bundles, and SDK configuration.

See Mobile EMV SDK page for platform requirements.

2

Pair a VP3300 reader over Bluetooth

Present the built-in pairing flow when the user needs to connect a reader.

Pair a reader

let pairingVC = ClearentUIManager.shared.pairingViewController(completion: {})
navigationController?.present(pairingVC, animated: true)

The pairing flow:

1. Prompts the user to wake the reader.
2. Scans for nearby VP3300 devices.
3. Guides the user through selection and connection.
4. Handles retries and connection errors.

3

Present the payment screen

Use the built-in payment view controller to start a card-present payment or manual card entry flow.

Start a payment

ClearentUIManager.shared.cardReaderPaymentIsPreferred = true
let transactionVC = ClearentUIManager.shared.paymentViewController(
    paymentInfo: PaymentInfo(amount: 20.0),
    completion: {}
)
navigationController?.present(transactionVC, animated: true)

Use this flow to:

1. Pass a PaymentInfo object with the required amount.
2. Prefer the card reader when it is available.
3. Fall back to manual entry when needed.
4. Receive a transaction JWT after successful tokenization.

Submit the JWT as the mobilejwt header in your payment API request.

4

Support manual card entry

Manual entry works as a fallback when the reader is unavailable or the transaction cannot continue on the device.

The flow collects:

• Card number, expiration date, and security code
• Optional billing and order details
• Any additional metadata required in PaymentInfo

5

Open the settings screen

Use the settings screen to manage readers and app-level payment options.

Open settings

let settingsVC = ClearentUIManager.shared.settingsViewController(completion: {})
navigationController?.present(settingsVC, animated: true)

From settings, users can:

• View the current reader
• Access recently paired readers
• Configure offline behavior
• Manage e-mail receipt preferences

You can also read saved reader details in code:

Read reader details

let currentReader = ClearentWrapperDefaults.pairedReaderInfo
let recentReaders = ClearentWrapperDefaults.recentlyPairedReaders

You can receive reader updates with:

Reader status callback

ClearentUIManager.configuration.readerInfoReceived = { reader in
    // Update your UI with reader status
}

6

Enable offline mode and supporting features

Enable offline mode during SDK initialization by providing offlineModeEncryptionKeyData.

When offline mode is enabled:

• Transactions can be stored locally
• Users can upload stored transactions later
• Upload reports are available in Settings
• Signatures can also be stored and uploaded later

Core features

Built-in payment flows

Payment UI includes prebuilt flows for:

• Reader pairing
• Payment initiation
• Manual card entry
• Reader and receipt settings

Signature capture

When enabled, Payment UI can prompt for a customer signature after a successful transaction. The SDK resizes, encodes, and uploads the signature to the backend. If the upload fails, the SDK supports retry behavior.

E-mail receipts

If enabled, Payment UI prompts the user for an e-mail address after a successful transaction.

Tips

If tip collection is enabled on the merchant account, Payment UI displays a tip selection step during checkout.

Offline support

Payment UI supports store-and-forward behavior when connectivity is unavailable. Users can review and process saved transactions later from the settings screen.

UI customization

You can align Payment UI with your app branding by customizing:

• Fonts
• Colors
• Text content

Enhanced messaging

Payment UI can display clearer transaction, and reader prompts through the bundled messaging resources.

To use enhanced messaging:

1. Include ClearentIdtechMessages.bundle in your app resources.
2. Add the bundle in Build Phases → Copy Resources.
3. Make sure enhancedmessages-v1.txt is available in that bundle.

Choose Payment UI or build your own UI

Options 1: Choose Payment UI when you want the fastest path to an iOS card-present experience.

Option 2: Choose a custom UI when you need:

• Full control over screen layout
• Custom navigation and app states
• A deeper integration with lower-level wrapper APIs

If you want custom UI control, start with Mobile EMV SDK.

Related topics

• See Payment Processing to compare Xplor Pay payment integrations.
• See Mobile EMV SDK for framework requirements and lower-level SDK details.
• See Payment UI quick start for a quick integration path.