DocsAPI Reference

Setting Up the Entitlement for Tap to Pay on iPhone

Learn how to request and configure the Tap to Pay on iPhone entitlement from Apple, which is required to enable contactless payment processing in your iOS application.

Get started with Koard

Overview

The Tap to Pay on iPhone entitlement is a managed capability that Apple provides to authorized Payment Service Providers (PSPs) and their partners. This entitlement allows your app to use Apple's ProximityReader framework to accept contactless payments directly on iPhone.

This guide covers the entitlement request process, configuration steps, and verification procedures based on Apple's official documentation.

What you learn

In this guide, you'll learn:

  • How to request the Tap to Pay entitlement from Apple
  • How to configure the entitlement in your Apple Developer account
  • How to add the entitlement to your Xcode project
  • How to verify the entitlement is properly configured
  • How to handle entitlement requirements for development and distribution
Prerequisites

Before you begin, ensure you have:

  • Apple Developer Account (organization-level account required)
  • Account Holder Access (entitlement requests must be made by the account holder)
  • PSP Partnership (your organization must be an authorized Payment Service Provider or partner)
  • Xcode 14.0 or later (for project configuration)
  • App ID Created (your app identifier must be registered in Apple Developer)
  • Sandbox Apple Account signed in on test device (dedicated iPhone running Developer Mode for entitlement validation)

Keep a Test iPhone Ready: Entitlement validation requires running builds on a physical test device signed in with your Sandbox Apple Account. Do not rely on production Apple IDs for these flows.

Requesting the Entitlement

The Tap to Pay on iPhone entitlement must be requested through Apple's developer portal. This process is handled by Apple and requires approval.

Access Apple Developer Portal
  1. Log in to your Apple Developer account as the account holder
  2. Navigate to Certificates, Identifiers & Profiles
  3. Select your organization if you have multiple accounts

Important: Only the account holder can request the Tap to Pay entitlement. Team members or admins cannot submit this request.

Request Tap to Pay Entitlement
  1. Go to Identifiers section
  2. Select your App ID (or create one if needed)
  3. Navigate to Additional Capabilities
  4. Find "Tap to Pay on iPhone" in the list of capabilities
  5. Click "Request" or "Enable" to submit your request
Wait for Approval

Apple will review your request and typically respond within one to two business days. You'll receive an email notification when the entitlement is approved or if additional information is needed.

Processing Time: The approval process typically takes 1-2 business days. You must start with the development certificate to access Apple's CERT environment.

Verify Entitlement Status

Once approved:

  1. Return to Certificates, Identifiers & Profiles
  2. Select your App ID
  3. Check Additional Capabilities
  4. Verify "Tap to Pay on iPhone" appears under Managed Capabilities

The entitlement will now be available for use in your provisioning profiles.

Configure Your App ID

After receiving approval, configure your App ID to include the entitlement:

Enable the Capability

  1. Navigate to Certificates, Identifiers & Profiles > Identifiers
  2. Select your App ID
  3. Scroll to Additional Capabilities
  4. Enable "Tap to Pay on iPhone"
  5. Save your changes

The capability will now be available for your App ID and can be included in provisioning profiles.

Add Entitlement to Your Xcode Project

Once the entitlement is approved and configured in your Apple Developer account, add it to your Xcode project:

Create Entitlements File
  1. Open your project in Xcode
  2. Select your project in the Project Navigator
  3. Choose File > New > File
  4. Select Property List under Resource
  5. Name the file [YourProjectName].entitlements
  6. Add it to your app target
Configure Build Settings
  1. Select your project in the Project Navigator
  2. Select your app target
  3. Go to Build Settings tab
  4. Search for "Code Signing Entitlements"
  5. Set the path to [YourProjectName].entitlements
Add Entitlement Key
  1. Open the .entitlements file in Xcode
  2. Add the following key-value pair:
<key>com.apple.developer.proximity-reader.payment.acceptance</key>
<true/>

The file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.proximity-reader.payment.acceptance</key>
    <true/>
</dict>
</plist>
Update Provisioning Profile
  1. In Xcode, go to Signing & Capabilities
  2. Select your development team
  3. Xcode will automatically download a new provisioning profile that includes the entitlement
  4. Verify the entitlement appears in the Capabilities section

Note: If Xcode doesn't automatically update the provisioning profile, you may need to manually regenerate it in the Apple Developer portal.

Verify Entitlement Configuration

After configuring the entitlement, verify it's properly set up:

Check in Xcode

  1. Select your project in Xcode
  2. Select your app target
  3. Go to Signing & Capabilities tab
  4. Verify "Tap to Pay on iPhone" appears in the Capabilities section

Verify in Code

You can programmatically verify the entitlement is present by checking the readerIdentifier property:

import ProximityReader


do {
let readerIdentifier = try await ProximityReader.readerIdentifier
print("Entitlement verified: (readerIdentifier)")
// Entitlement is present and valid
} catch {
print("Entitlement error: (error)")
// Handle notAllowed error if entitlement is missing
}

If the entitlement is missing, readerIdentifier will throw a notAllowed error.

Development vs Distribution Entitlements

The Tap to Pay entitlement has different requirements for development and distribution:

Development Entitlement

  • Purpose: Internal testing and development
  • Provisioning: Development provisioning profiles
  • Distribution: Ad-hoc distribution via .ipa files
  • Testing: Limited to registered test devices

Distribution Entitlement

  • Purpose: TestFlight and App Store distribution
  • Provisioning: Distribution provisioning profiles
  • Distribution: TestFlight beta testing and App Store submissions
  • Testing: Available to all TestFlight testers and App Store users

Important: If you've already received the development entitlement and need to distribute via TestFlight or the App Store, you must request the distribution entitlement separately. Respond to the original approval email from Apple to request the distribution entitlement.

Troubleshooting

Entitlement Not Appearing

If the entitlement doesn't appear in your Apple Developer account:

  • Verify account holder status: Only the account holder can request entitlements
  • Check PSP partnership: Ensure your organization is authorized as a PSP or partner
  • Contact Apple: Reach out to Apple Developer Support if the entitlement is not available

Entitlement Not Working in Xcode

If the entitlement doesn't work in Xcode:

  • Verify provisioning profile: Ensure your provisioning profile includes the entitlement
  • Check entitlements file: Verify the .entitlements file contains the correct key
  • Update provisioning profile: Regenerate your provisioning profile in Apple Developer portal
  • Clean build folder: In Xcode, go to Product > Clean Build Folder

Reader Identifier Returns Error

If readerIdentifier throws a notAllowed error:

  • Verify entitlement in Apple Developer: Check that the entitlement is approved and enabled
  • Check provisioning profile: Ensure the profile includes the Tap to Pay capability
  • Verify device registration: For development, ensure test devices are registered
  • Check code signing: Verify your app is signed with the correct provisioning profile

Additional Resources

See also