HCE-based contactless transactions for banking and wallet apps in the European Economic Area

iOS 17.4 introduces new APIs for developers to support contactless payment transactions from within their banking or wallet apps using host card emulation (HCE). Users based in the European Economic Area (EEA) with an iPhone running iOS 17.4 or later can initiate in-person payment transactions from a banking or wallet app at compatible NFC terminals or mobile devices that accept contactless payments. HCE apps, which are software-based solutions, can be more susceptible to attack vectors whereby payment transaction tokens and other sensitive financial data may be compromised, including through exposure to untrusted and potentially malicious entities.

To help protect user privacy and security on iPhone, developers who want to build HCE payment capabilities into their banking or wallet app using these APIs will need to apply for the HCE Payments Entitlement. This ensures that only authorized app developers who meet certain industry and regulatory requirements, and commit to ongoing security and privacy standards can access these APIs.

How it works

  • NFC payments. Users of participating third-party banking or wallet apps can initiate NFC transactions from within the app with compatible NFC terminals.
  • Default app settings. Users can choose any eligible app as their default contactless payments app which will enable the app to support Field detect and Double-click features.
  • Field detect. The default contactless payments app automatically launches when the user places the device in the presence of a compatible NFC terminal and after user authentication (if the iPhone is locked).
  • Double-click. The default contactless payments app automatically launches when the user double-clicks the side button (for Face ID devices) or the Home button (for Touch ID) and after user authentication (if the iPhone is locked).
  • Payment support for non-default apps. Eligible apps running in the foreground can prevent the system default contactless app from launching and interfering with the payment.

Requesting the HCE Payments Entitlement

If you’d like your banking or wallet app to support in-store NFC payments within the EEA, you’ll need the HCE Payments Entitlement. This entitlement ensures that the developer requesting access to the APIs will adhere to certain industry and regulatory requirements — such as being licensed to offer payment services in the EEA, conforming to industry security standards (for example, Payment Card Industry Data Security Standards and EMVCo), have valid agreements with an authorized payment service provider, have network certifications in apps they integrate these capabilities with, and commit to ongoing security and privacy standards to access and use these capabilities.

To get started, submit the entitlement request form. You’ll need to be an Account Holder in the Apple Developer Program, provide the additional details listed below, and agree to the entitlement’s terms and conditions.

To be eligible for the entitlement, you must:

  • Be established in the EEA.
  • Be licensed to provide payment services in the EEA or plan to work with licensed entities to offer payment services in the EEA.
  • Support in-store NFC payments use cases.
  • Use the entitlement to provide capabilities only to users based in the EEA.
  • Follow the HCE requirements and experience guidelines below.

You’ll need to provide the following details with your submission request. Please make sure your request is as complete as possible to avoid delays.

App name. Enter your app’s name, then describe its primary purpose and how it works.

Bundle ID. Enter the bundle ID (the app’s unique identifier) that you plan to use. Entitlement requests are per bundle ID and assigned entitlements can only be used with the single binary associated with the bundle ID.

Specify intended use: Describe how your app will use the entitlement.

List AID or RID prefixes: Enter a list of Application Identifier (AIDs) or Registered Application Provider Identifiers (RIDs) associated with your app.

Providing an HCE payment experience within your app

Requirements

  • You must be established in the EEA.
  • Your app must be for iOS users in eligible EEA markets and you plan to distribute it to iOS users in the EEA for making in-store NFC payments.
  • Your app must have the ability to support ISO 14443-4 and ISO 7816-4 commands in order to communicate with the NFC terminal.
  • You must have a license to offer payment services in the EEA or have a valid and binding agreement with a payment service provider (PSP) that’s licensed or authorized to offer payment services in the EEA.
  • You must meet all the security standards and privacy requirements that apply to the processing of personal data in the EEA and to the HCE app and your business, including security standards published by the PCI DSS and EMVCo, GDPR, or other applicable national law.
  • You must maintain (or have in place before the HCE Payments Entitlement is granted) appropriate written policies and procedures for:
    1. The processing of personal data, including disclosure to third parties, and
    2. The disclosure, processing, and remediation of potential vulnerabilities in your HCE app and back-end HCE infrastructure, and will have in place a process to promptly and without undue delay notify Apple of any any security incident or actively exploited vulnerability in your HCE app or HCE back-end infrastructure.

Design guidelines

Display the in-app NFC presentment sheet

Eligible iOS apps running on supported iPhone models can use the proposed solution to present an eligible credential to a compatible near-field communication (NFC) terminal. In the iOS app, you can invoke an NFC presentment sheet with customizable text whenever users are about to make a contactless transaction.

Use familiar terminology and provide brief instructional text

NFC may be unfamiliar to some people. To make it approachable, avoid referring to technical, developer-oriented terms like NFC, Core NFC, near-field communication, etc. Instead, use friendly, conversational terms that most people will understand. For example:

Use Don’t use
Hold your iPhone near the [object name] to make a payment. To use NFC payments, tap your phone to the [object name].

Presentment Intent Assertion

In order to enable a seamless payment experience, eligible app developers can prevent the system default contactless app from launching and interfering with the payment.

You can acquire a presentment intent assertion to suppress the default contactless app when the user expresses an active intent to perform an NFC transaction, like choosing a payment credential or activating the presentment UI. You can only invoke the intent assertion capability when your app is in the foreground.

The intent assertion expires if any of the following occur:

  • The intent assertion object deinitializes
  • Your app goes into the background
  • 15 seconds elapse

After the intent assertion expires, your app will need to wait 15 seconds before acquiring a new intent assertion.

Important: Use of the intent assertion API outside of payment intent, or other abuse of this API, is against Apple policy and could result in removal from the App Store and revocation of the entitlement to access the NFC presentment UI.

Only show the in-app NFC presentment sheet for eligible devices and users

Before presenting the NFC presentment sheet for contactless payments, we recommend using the isEligible iOS API to validate eligibility for contactless payment experiences. If isEligible returns False, don’t invoke the presentment sheet.

Distinguish this solution from Apple Pay and Apple Wallet

The HCE-based solution is independent of Apple Pay and Apple Wallet, so to avoid any customer confusion between Apple Pay and this solution, it’s essential to distinguish the presentment experience when leveraging this solution. Avoid displaying an Apple Pay or Apple Wallet mark in the payment button that launches the in-app NFC presentment sheet for HCE payments.

Configuring and enabling the entitlement in Xcode

Once you receive an email confirmation that the entitlement was assigned to your account and you’ve configured the app ID in Certificates, Identifiers & Profiles to support this entitlement, you’ll need to update your Xcode project, entitlements plist file, and Info.plist file to list the entitlement and metadata. The entitlement is compatible with iOS 17.4 and later on iPhone.

  1. In the Project navigator, select the .entitlements file.
  2. In the entitlements plist file, add a new entitlement key pair by holding the pointer over the Entitlements File row and clicking the add button (+).
  3. Provide the following values for this entitlement:
    1. Key: com.apple.developer.nfc.hce
      1. Type: BOOL
      2. Value: TRUE/FALSE
    2. Key: com.apple.developer.nfc.hce.iso7816.select-identifier-prefixes
      1. Type: Array of String
      2. Value: A list of AIDs or RIDs associated with the payment applications intended to be used with the iOS app.
      3. Examples:
        1. 325041592E5359532E4444463031 - PPSE
        2. A0000000032020 - Visa
        3. A0000000042010 - Mastercard
    3. Key: com.apple.developer.nfc.hce.default-contactless-app
      1. Type: BOOL
      2. Value: TRUE/FALSE

On the next build to your device or distribution request in Xcode Organizer, Xcode will detect that the .entitlements file and cached provisioning profile don’t match, and will request a new provisioning profile based on the latest app ID configuration to complete the code signing process.

Testing requirements

To test HCE-based contactless transactions, you’ll need to test with an iPhone and NFC hardware within the EEA. CardSession requires the presence of an NFC reader, which isn’t supported in Simulator, to perform an ISO 7816 card emulation session. Please make sure:

  • Your iPhone is running iOS 17.4 or later
  • You’ve signed in with an Apple ID based in an EEA country or region

Documentation and resources