Accept payments via Tap to Pay on iPhone - iOS

The Revolut Tap to Pay SDK for iOS allows merchants to accept contactless payments directly on iPhone using Apple's Tap to Pay technology. This guide covers the client-side integration: installing the SDK, implementing the token provider, initialising the SDK, and accepting payments.

The SDK wraps Apple's ProximityReader framework and Revolut's payment infrastructure into a single integration. It handles device pairing, order creation, payment processing, and UI presentation - your app provides the token provider and calls the payment methods.

How it works​

From an implementation perspective, the Tap to Pay SDK works with the following components:

1. Server-side: Your server holds the merchant's long-lived OAuth tokens and provides short-lived device tokens to the iPhone app. For setup details, see Get started.
2. Client-side: The SDK (RevolutTapToPayKit) is initialised with a token provider that fetches short-lived device tokens from your backend. The SDK handles Apple ProximityReader pairing, Card Reader Token management, order creation, payment processing, and presents the payment UI.
3. Endpoint for webhooks: Set up an endpoint to receive webhook events from the Merchant API to track the payment lifecycle. Webhooks are the only reliable way to get the final, authoritative payment status - client-side callbacks are for UI updates only. For more information, see: Use webhooks to keep track of the payment lifecycle.

The payment flow works as follows:

1. Your app calls the SDK to start a payment session with an amount and currency.
2. The SDK requests a short-lived device token from your backend via the token provider.
3. The SDK handles Apple ProximityReader pairing and Card Reader Token management.
4. The SDK creates an order and processes the payment through Revolut's infrastructure.
5. The customer taps their contactless card or digital wallet on the iPhone.
6. The SDK returns the payment result and an optional receipt to your app.
7. Your server receives webhook notifications to confirm the final payment state.

The SDK offers two payment methods: Tap to Pay (contactless card or wallet) and QR code. In performPayments (multi-payment mode), the merchant chooses between them for each transaction. In performPayment (single payment), the SDK uses Tap to Pay and automatically falls back to QR code if contactless isn't available.

What the SDK handles​

The SDK manages the following internally - you should not call these endpoints directly:

What your app handles​

Your app remains responsible for the user experience around the SDK:

Implementation overview​

1. Set up the Apple entitlement
2. Install the SDK
3. Implement the token provider
4. Initialise the SDK
5. First-time setup (optional)
6. Receive payments
7. Handle payment results

Before you begin​

Before you start this tutorial, ensure you have completed the Get started guide and have the following:

• Your application is registered and submitted to production in the Developer Portal
• The merchant has API & integrations permission enabled on their Revolut Business account
• Your backend serves short-lived device tokens to the iOS app (grant_type=exchange_token)
• Your backend can refresh the merchant's OAuth tokens when they expire (grant_type=refresh_token)
• Apple ProximityReader entitlement requested and approved

Integrate the Tap to Pay SDK​

The following steps walk you through the client-side integration: setting up the Apple entitlement, installing the SDK, implementing the token provider that connects to your backend, initialising the SDK, and accepting payments.

1. Set up the Apple entitlement​

Before the SDK can use Apple's Tap to Pay on iPhone technology, you must set up the ProximityReader entitlement in your Apple Developer account and add it to your Xcode project.

1. Follow Apple's guide to set up the entitlement for Tap to Pay on iPhone.

2. Add the entitlement to your app's capabilities in Xcode under Signing & Capabilities.

   RevolutTapToPayApp.entitlements

   com.apple.developer.proximity-reader.payment.acceptance

   Copy

2. Install the SDK​

We recommend using CocoaPods to integrate the SDK into your Xcode project.

1. Ensure you have the latest version of CocoaPods installed.

2. If your project doesn't have a Podfile yet, create one by running:

   pod init

   Copy

3. Add the following line to your Podfile:

   Podfile

   pod 'RevolutPayments/RevolutTapToPay'

   Copy

4. At the end of your Podfile, add this configuration:

   Podfile

   post_install do |installer|
       installer.generated_projects.each do |project|
           project.targets.each do |target|
               target.build_configurations.each do |config|
                   config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '16.4'
               end
           end
       end
   end

   Copy

5. Install the dependencies:

   pod install

   Copy

6. From now on, open your project using the .xcworkspace file rather than the .xcodeproj file.

7. To ensure the SDK uses the latest version, run:

   pod update RevolutPayments/RevolutTapToPay

   Copy
   To update the SDK to a newer version re-run this command.

3. Implement the token provider​

The SDK needs an access token to authenticate its API calls. Instead of receiving a static credential, the SDK calls a TokenProviderProtocol implementation whenever it needs a fresh token. Your implementation depends on which integration architecture you chose:

import RevolutTapToPay

final class TokenProvider: TokenProviderProtocol {
    func fetchAccessToken() async throws -> SdkTokenApiDto {
        // Call your backend endpoint that returns a short-lived device token.
        // Your backend uses `grant_type=exchange_token` to obtain it
        // from the merchant's OAuth `access_token` (see Get started: Step 3).
        let response = try await backendClient.fetchDeviceToken()
        return SdkTokenApiDto(accessToken: response.accessToken)
    }
}

When the SDK requests a new token​

The SDK calls fetchAccessToken() in two situations:

1. First API call - no token has been provided yet.
2. Token expired - the SDK received an unauthorised error, meaning the current device token is no longer valid.

4. Initialise the SDK​

Create an instance of RevolutTapToPayKit - the main entry point to all SDK flows. Create it where it's accessible to the code that triggers payments - for example, as a property on a view model or a shared service. You only need one instance per app session.

import RevolutTapToPay

final class MenuViewModel {
    private lazy var tapToPayKit = RevolutTapToPayKit(
        clientId: Config.clientId,
        environment: .production,
        tokenProvider: TokenProvider(),
        onLogout: {
            // The merchant is no longer authorised to use the SDK.
            // This means consent was revoked, not granted, or the app
            // permission was removed in the Developer Portal.
            // Stop SDK usage and prompt the merchant to re-authorise
            // via the OAuth consent flow, or fall back to other payment methods.
        }
    )
}

5. First-time setup (optional)​

You can optionally call performFirstTimeSetup to guide the merchant through the initial setup before accepting payments. This method:

1. Runs the steps necessary to set up Apple's ProximityReader framework for operation, including accepting terms and conditions.
2. Optionally presents an introduction screen giving a short description of Tap to Pay on iPhone capabilities.
3. Gives the merchant an opportunity to run a test payment. The test payment behaves exactly like performPayment, with a predefined amount of 1 currency unit (e.g., £0.01).

tapToPayKit.performFirstTimeSetup(
    shouldShowIntro: true,
    currency: "GBP",
    merchantName: "City Taxi Co.",
    completion: { [self] receipt, result in
        switch result {
        case .success:
            // Setup completed. If a test payment was made, receipt is available.
            if let receipt {
                // receipt.url contains a URL for sharing the test payment receipt
                print("Test payment receipt URL: \(receipt.url)")
            }
        case .failure(let error):
            // Setup or test payment failed.
            print("Setup failed: \(error)")
        }
    }
)

6. Receive payments​

The SDK provides two methods for accepting payments. Both present their own UI and return results via callbacks.

tapToPayKit.performPayment(
    amount: 10_00,
    currency: "GBP",
    description: "Taxi fare - Trip #1234",
    merchantName: "City Taxi Co.",
    onDidCharge: { [self] receipt, result in
        switch result {
        case .success:
            // Payment completed. Receipt contains a URL for sharing.
            if let receipt {
                print("Receipt URL: \(receipt.url)")
            }
        case .failure(let error):
            // Payment failed. Handle the error.
            print("Payment failed: \(error)")
        }
    },
    completion: { [self] in
        // The SDK's UI has been dismissed.
        // Continue with any UI updates in your app.
        print("Payment flow completed")
    }
)

7. Handle payment results​

Both performPayment and performPayments return results through two callbacks with different timing:

onDidCharge: { [self] receipt, result in
    switch result {
    case .success:
        // Payment successful - update your order/POS state
        if let receipt {
            // Present receipt sharing options to the merchant
            let activityVC = UIActivityViewController(
                activityItems: [receipt.url],
                applicationActivities: nil
            )
            present(activityVC, animated: true)
        }
    case .failure(let error):
        // Payment failed - inform the merchant
        showAlert(title: "Payment failed", message: error.localizedDescription)
    }
},
completion: { [self] in
    // SDK UI dismissed - continue app flow
    navigationController?.popToRootViewController(animated: true)
}

Implementation checklist​

Use this checklist to verify that your Tap to Pay integration is correctly implemented before going live.

SDK setup​

• ProximityReader entitlement (com.apple.developer.proximity-reader.payment.acceptance) added to your Xcode project.
• SDK installed via CocoaPods with correct deployment target (iOS 16.4+).
• SDK initialised with the correct clientId and .production environment.
• TokenProviderProtocol implemented and calls your backend for device tokens.
• onLogout handler implemented (notifies backend or prompts merchant to re-authorise).
• RevolutTapToPayKit instance stored accessibly (e.g., view model property or shared service).

Payment flow​

• performPayment tested with a real test amount.
• performPayments tested with the amount entry UI.
• performFirstTimeSetup tested (optional, but recommended for first-time users).
• Payment result handling tested for success, failure, and cancellation scenarios.
• onDidCharge and completion callbacks handled with correct timing expectations.
• Receipt URL sharing tested.
• QR code payment fallback verified (test with a non-contactless card or by triggering a Tap to Pay unavailability scenario).
• Two consecutive unauthorised errors trigger onLogout (test with an expired or invalid token).

Backend​

• Device token endpoint implemented and serving tokens to the iOS app (grant_type=exchange_token).
• Access token refresh implemented (grant_type=refresh_token).
• Webhook endpoint receives and processes payment status events.

What's next​