Tap to Pay on iPhone

Learn how to integrate Tap to Pay on iPhone with the iOS SDK, verify device support, and launch contactless payments.

Tap to Pay on iPhone lets merchants accept contactless payments directly on a supported iPhone. No external card reader is required.

The iOS SDK (ClearentIdtechIOSFramework) provides a ready-made Tap to Pay experience through TapToPayRootView and tapToPayViewController(...).

Use Tap to Pay when you want:

• A reader-free contactless checkout
• Faster integration with minimal UI work
• Built-in handling of Apple Tap to Pay workflows

At a glance

• Integration: CocoaPods
• Minimum iOS: 15.4 or later
• Recommended target: 15.6 or later
• UIKit entry point: tapToPayViewController(...)
• SwiftUI entry point: TapToPayRootView
• Device pre-check: verifyTapToPayDeviceSupport()
• Requirement: Initialize the SDK before use

Requirements

Before you use Tap to Pay, make sure you have:

Apple and device requirements

• A physical iPhone

Tap to Pay does not work on the Simulator.

• A supported iPhone that passes PaymentCardReader.isSupported
• iOS 15.4 or later
• Device passcode enabled
• NFC enabled

Apple developer requirements

• Proximity Reader Payment Acceptance entitlement
• Apple Developer Program approval
• Entitlement configured in:

  • App ID capabilities
  • App .entitlements file

Integration requirements

• A host iOS app using the iOS SDK (ClearentIdtechIOSFramework)
• Valid API credentials
• Network connectivity for payment processing

What the SDK handles

Tap to Pay manages the full payment experience, including:

• Device capability checks
• Apple merchant account linking and terms acceptance
• Proximity Reader session setup
• Contactless card reading
• Secure card tokenization
• Transaction processing
• Success and error screens
• Optional signature capture and e-mail receipts

What your app handles

Your app is responsible for:

• Initializing the SDK
• Creating the PaymentInfo object
• Launching the Tap to Pay flow
• Handling navigation after the payment completes

Xcode project setup

Proximity Reader framework

The SDK uses Apple’s Proximity Reader framework internally. No manual setup is required beyond standard linking.

Add Apple entitlement

Add the Proximity Reader Payment Acceptance entitlement in:

• Apple Developer Portal
• The app’s .entitlements file

Without this entitlement, Tap to Pay fails at runtime.

Initialize the SDK

SDKSetup.swift

import ClearentIdtechIOSFramework

let config = ClearentUIManagerConfiguration(
    baseURL: "BASE_URL",
    apiKey: "YOUR_API_KEY",
    publicKey: nil,
    enableEnhancedMessaging: true,
    signatureEnabled: true,
    softwareType: "YourAppName",
    softwareTypeVersion: "1.0.0"
)

ClearentUIManager.shared.initialize(with: config)
UIFont.loadFonts()

Verify device support

Check device compatibility before you launch Tap to Pay.

verifyTapToPayDeviceSupport()

TapToPayAvailability.swift

@available(iOS 15.4, *)
func checkTapToPayAvailability() {
    let result = ClearentUIManager.shared.verifyTapToPayDeviceSupport()

    if result.isSupported {
        // Enable Tap to Pay
    } else {
        print(result.errorMessage ?? "Tap to Pay not supported.")
    }
}

What it checks

• Running on Simulator
• Unsupported device model
• PaymentCardReader.isSupported

Return type

Property	Type	Description
isSupported	Boolean	Indicates whether the current device supports Tap to Pay. If true, you can safely launch the Tap to Pay flow.
errorMessage	String	A localized message that explains why Tap to Pay is not supported. This value is nil when isSupported is true.

isTapToPaySupported

TapToPaySupport.swift

let canUseTapToPay = ClearentUIManager.shared.isTapToPaySupported

Recommended pattern

CheckoutViewController.swift

@IBAction func payWithTapToPay(_ sender: UIButton) {
    let support = ClearentUIManager.shared.verifyTapToPayDeviceSupport()

    guard support.isSupported else {
        showAlert(message: support.errorMessage ?? "Unavailable.")
        return
    }

    presentTapToPay(amount: 49.99)
}

Launch Tap to Pay

Create a PaymentInfo object

PaymentInfo.swift

let paymentInfo = PaymentInfo(
    amount: 25.99,
    customerID: "CUST-001",
    invoice: "INV-12345",
    orderID: "ORD-98765",
    softwareType: "YourAppName",
    softwareTypeVersion: "1.0.0"
)

PaymentInfo properties

Property	Type	Required?	Description
amount	Double	Required	The total transaction amount to charge the customer. Use standard currency format, for example 25.99.
customerID	String	Optional	A unique identifier for the customer in your system.
invoice	String	Optional	The invoice number associated with the transaction.
orderID	String	Optional	A unique identifier for the order.
softwareType	String	Optional	The name of the host application or integration.
softwareTypeVersion	String	Optional	The version of your application.

UIKit (recommended)

Use tapToPayViewController(...) when your app already uses UIKit.

PaymentViewController.swift

func presentTapToPay(amount: Double) {
    let paymentInfo = PaymentInfo(amount: amount)

    let vc = ClearentUIManager.shared.tapToPayViewController(
        paymentInfo: paymentInfo
    ) { error in
        if let error = error {
            print("Dismissed with error: \(error)")
        } else if TapToPayFlowManager.shared.state == .active {
            print("Payment successful")
        }
    }

    present(vc, animated: true)
}

SwiftUI integration

Use TapToPayRootView when your checkout flow is built with SwiftUI.

CheckoutView.swift

struct CheckoutView: View {
    @State private var showTapToPay = false

    var body: some View {
        Button("Pay with Tap to Pay") {
            showTapToPay = true
        }
        .fullScreenCover(isPresented: $showTapToPay) {
            TapToPayRootView(
                paymentInfo: PaymentInfo(amount: 25.99),
                onDismiss: { showTapToPay = false }
            )
        }
    }
}

UIKit (manual hosting)

Use this only if you need to host TapToPayRootView inside a UIKit screen yourself.

ManualTapToPayPresenter.swift

func presentTapToPayManual(amount: Double) {
    let view = TapToPayRootView(
        paymentInfo: PaymentInfo(amount: amount),
        onDismiss: { self.dismiss(animated: true) }
    )

    let hosting = UIHostingController(rootView: view)
    hosting.modalPresentationStyle = .fullScreen
    present(hosting, animated: true)
}

Tap to Pay on iPhone process flow

1

Verify device support

The SDK checks:

• Device compatibility
• NFC availability
• Passcode status

The flow stops if the device does not meet Apple requirements.

2

Initialize Tap to Pay session

The SDK requests a session token from backend services. This token is used to initialize the Apple Proximity Reader session.

3

Link merchant account

If the merchant has not accepted Apple Terms:

• The SDK displays the terms sheet
• The user reviews and accepts

Returning users skip this step.

4

Prepare the reader session

The SDK:

• Initializes the proximity reader
• Prepares the device to accept a contactless payment

5

Read the contactless card

The SDK:

• Prompts the user to hold a card near the iPhone
• Displays Apple’s native card read interface
• Captures encrypted card data

6

Process the payment

The SDK:

• Tokenizes the encrypted card data
• Sends the payment request to backend services
• Processes the transaction securely

7

Show the result

The SDK displays:

• Success screen for approved transactions
• Error screen with a retry option for failures

8

Run optional post-payment steps

Depending on your configuration:

• Signature capture
• E-mail receipt collection

Screens

Tap to Pay includes the following screens:

1. Landing screen
2. Enable Tap to Pay
3. Card read screen
4. Processing screen
5. Success or error screen
6. Signature screen
7. Receipt screen

User actions

Screen	When shown	User action
Landing	First-time setup	Review the information, then tap Enable Tap to Pay on iPhone to continue.
Loading	During setup and card read	Hold the contactless card or device near the iPhone until the read completes.
Authorizing	After card read	Wait while the payment is processed.
Success	Payment approved	Review the transaction details, then tap Done.
Error	Payment fails or is interrupted	Review the error message, then choose Retry or Cancel.
Signature	After a successful payment, if enabled	Ask the customer to sign on the screen, then confirm.

Returning users skip the setup screens and go directly to payment.

Error handling

Card reader errors

Examples:

• NFC disabled
• Card removed too early
• Reader busy

The SDK displays a system alert with these buttons:

• Select Retry to retry the payment.
• Select Cancel to exit the flow.

Transaction errors

Examples:

• Network failure
• Invalid token
• Payment declined

The SDK shows an error screen with retry options.

Common failure causes

Issue	What the user sees on the device	Cause
Unsupported device	A message indicating that Tap to Pay is not available on this device. The payment option may be disabled or hidden.	The device is a Simulator or an iPhone model that does not support Tap to Pay.
Passcode disabled	A prompt asking the user to enable a device passcode before continuing.	The device does not have a passcode set, which is required for security.
NFC disabled	A message asking the user to enable NFC or bring the device closer, but payment does not start.	NFC is turned off or not functioning in device settings.
Account linking cancelled	The Tap to Pay setup screen closes or shows a message indicating setup was not completed.	The user declined Apple Terms and Conditions during account linking.
Network error	A message indicating that the connection failed or the payment could not be processed.	The device has no internet connection or unstable network connectivity.
Payment declined	A message stating that the payment was declined, with an option to try again or use a different payment method.	The card issuer rejected the transaction (for example, insufficient funds or security checks).

API reference

API	Type	Description
verifyTapToPayDeviceSupport()	Method	Runs a device compatibility check.
isTapToPaySupported	Property	Returns a quick support check.
tapToPayViewController	Method	Launches the UIKit payment flow.
TapToPayRootView	View	Launches the SwiftUI payment flow.
TapToPayDeviceSupportResult	Struct	Contains support status and an optional error message.
TapToPayFlowManager.state	Enum	Represents the current payment state.

Related topics

• See Payment Processing to compare Xplor Pay payment integrations.
• See iOS SDK for framework requirements and lower-level SDK details.
• See Proximity Reader | Apple Developer Documentation for Apple developer requirements.
• See Mobile EMV SDK for in-person payments using a Bluetooth card reader.