Adding Support for Tap to Pay on iPhone

Enable Tap to Pay on iPhone to allow merchants to accept contactless payments directly on their iPhone without additional hardware.

If you're ready to start developing, see our iOS SDK installation guide.

Get started with Koard

Enable the Tap to Pay Entitlement

Enabling the Tap to Pay Entitlement is a critical step that is handled by Apple. Typically, you will need to request the entitlement from Apple through their developer portal.

Requesting Tap to Pay Entitlement from Apple

To enable Tap to Pay on iPhone, follow these steps:

1. Log in to your Apple Developer account as the account holder
2. Navigate to Certificates, Identifiers & Profiles
3. Select Tap to Pay on iPhone Entitlement and submit a request
4. Wait for approval - Apple will add the entitlement under Managed Capabilities

Configure Your Xcode Project

Once you have the entitlement, configure your Xcode project:

1. Enable Tap to Pay Capability

1. Sign in to your Apple Developer Account
2. Create an App ID (if you don't have one already)
3. Go to Certificates, Identifiers & Profiles > Identifiers
4. Select your app and go to Additional Capabilities
5. Enable Tap to Pay on iPhone and save

2. Create a Provisioning Profile

1. Open Xcode and select your project
2. Navigate to Signing & Capabilities
3. Under Provisioning Profile, select Download Profile
4. Choose the new provisioning profile

3. Add Entitlements File

1. In Xcode, select your project in Project Navigator
2. Create a new Property List file (File > New > File > Resource)
3. Name the file [ProjectName].entitlements
4. Open Build Settings and locate Code Signing Entitlements
5. Set its value to the path of the .entitlements file

Open the .entitlements file and add the following key-value pair:

<key>com.apple.developer.proximity-reader.payment.acceptance</key>
<true/>

Testing in Developer Mode

To test the iOS app in developer mode, follow these additional steps:

Enable Developer Mode

1. On the test iPhone, go to Settings > Privacy & Security
2. Enable Developer Mode

Use a Sandbox Apple Account

The sandbox account must be:

• Freshly created in App Store Connect
• Signed into iCloud
• Linked to the test iPhone

Register a Test Device

1. Retrieve the UDID of the test device
2. Add the UDID to Allowed Devices in the Apple Developer account
3. Update the Provisioning Profile to include the allowed devices

Distribute via .ipa File

1. Create an .ipa build file in Xcode
2. Share the build with your internal team for testing

TestFlight and App Store Distribution

TestFlight beta testing and App Store submissions require a separate entitlement that allows distribution. If you've already completed your testing with the non-distribution entitlement, respond to the original email and re-request the Tap to Pay on iPhone Entitlement.

Testing Environment

Running a transaction in the cert environment will route payments to all the processor and card brands test environment. Transactions sent through this setup will NOT authorize a real transaction but will be production-like in terms of workflow.

Test Cards

Use these test cards to verify your integration:

• Test Card: 4242 4242 4242 4242
• Expiry: Any future date
• CVV: Any 3 digits

Production Deployment

Before going live:

1. Complete merchant verification in Koard MMS
2. Switch to production environment in your app configuration
3. Test with real payment methods (in a controlled environment)
4. Submit for App Store review with the distribution entitlement
5. Review scheme setup in Getting Ready for Production to ensure the correct API keys ship with your archive.

Card Reader Lifecycle in the SDK

Once the entitlement and provisioning are in place, the SDK manages the Apple ProximityReader card reader. After authenticating the merchant, link the account and prepare the reader before taking payments.

import KoardSDK

// 1. Check whether the merchant account is already linked to Apple Tap to Pay
let isLinked = try await KoardMerchantSDK.shared.isAccountLinked()

// 2. Link the account if needed (this requires user interaction)
if !isLinked {
    // Synchronous variant
    try KoardMerchantSDK.shared.linkAccount()
    // Or the async variant (recommended with Swift Concurrency)
    // try await KoardMerchantSDK.shared.linkAccountAsync()
}

// 3. Prepare the reader for accepting payments
try await KoardMerchantSDK.shared.prepare()

Monitor Reader Events and Status

Observe live reader events with the readerEvents async stream, and check status to see whether the reader is ready:

Task {
    for await event in KoardMerchantSDK.shared.readerEvents {
        print("Reader event: \(event.description)")
    }
}

// Current reader status
let status = KoardMerchantSDK.shared.status

Present the Tap to Pay Tutorial

On iOS 18 and later, you can present Apple's built-in "How to Tap" tutorial from a visible view controller:

if #available(iOS 18.0, *) {
    try KoardMerchantSDK.shared.presentTutorial(from: viewController)
}

Troubleshooting

Common Issues

• Entitlement Not Found: Ensure you've requested and received approval from Apple
• Provisioning Profile Issues: Make sure your provisioning profile includes the Tap to Pay capability
• Device Registration: Verify test devices are properly registered in your Apple Developer account
• Sandbox Account Issues: Use a fresh Apple ID created specifically for testing

Support

For technical issues with Tap to Pay integration:

• Check the Apple Best Practices guide
• Review Payment Configurations for advanced settings
• Contact Koard support for SDK-specific issues

See also

This wraps up the Tap to Pay setup. See the links below for next steps in your integration:

• Creating a Sandbox Apple Account - Set up test identities
• Installing the SDK - Complete SDK integration guide
• Running Payments - Implement payment processing
• Payment Lifecycle - Understand the complete payment flow
• Getting Ready for Production - Configure schemes for launch
• Apple Best Practices - Follow Apple's guidelines