DocsAPI Reference

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

What you learn

In this guide, you'll learn:

  • How to request the Tap to Pay entitlement from Apple
  • How to configure your Xcode project for Tap to Pay
  • How to set up testing in developer mode
  • How to distribute your app for testing and production
Prerequisites

Before you begin, ensure you have:

  • iOS 17.0 or later (minimum required version)
  • iPhone XS or later (supported hardware)
  • Apple Developer Account (organization-level account required)
  • Koard iOS SDK (installed in your project)
  • Valid merchant account (configured in Koard MMS)
  • Sandbox Apple Account signed in on test device (dedicated iPhone in Developer Mode)

Use a Dedicated Test iPhone: Keep your Sandbox Apple Account signed in on a separate test device. Production Apple IDs cannot complete Sandbox Tap to Pay transactions.

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

Processing Time: The process to get approval from Apple typically takes one or two business days. You will need to start with the development certificate to get access to the Apple CERT environment.

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/>

Additional Resources: More details on enabling the tap to pay entitlement can be found in Apple's Developer Documentation.

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

Important: Existing accounts attempting to test an App with Tap to Pay in cert mode will be blocked from creating a card reader session due to Apple's security policies.

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

Device Management: Any new test device will need to have the UDID uploaded and a NEW provisioning profile will need to be added anytime new devices are added. The app will then need a new archive file that will be shared with the new device.

Distribute via .ipa File

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

Testing Recommendation: It is highly recommended that you have a secondary iPhone or higher to test transactions. Otherwise, developer mode means that engineers will have to sign into a test account onto their own devices to test the mPOS app with Tap to Pay. This is a hard limitation set by Apple and has no workaround at the moment.

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.

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:

See also

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