Skip to main content

Setting up Tap to Pay on iPhone

When set up for your business, you can enable associates to accept payments via Tap to Pay on iPhone in Associate App for in-store purchases, without using a payment terminal. To learn how to use this payment option, see Choosing a payment option .

Customers can use a physical or digital form of payment that supports NFC. Credit cards that support Tap to Pay on iPhone, digital wallets like Apple Pay and Google Pay, or digital devices that support digital wallets (like the Apple Watch) are currently supported.

However, associates cannot use Tap to Pay on iPhone to process refunds or exchanges in Associate App.

NewStore manages this payment feature via an integration with Adyen as the payment service provider. The setup process requires you to enable Tap to Pay on iPhone in Adyen and setting the feature up in NewStore.

Pre-requisites​

Tap to Pay on iPhone is only available:

  • On iPhone XR, XS, SE Gen 2 and Gen 3, or later, running on iOS 15.5 or later
  • In the US on v1.16.1 and later of NewStore Associate App
  • In the UK on v1.36.0 and later of NewStore Associate App
  • In the NL (Netherlands) and AU (Australia) on v1.39.0 and later of NewStore Associate App
  • The US, UK, and NL support payments via MasterCard, Visa, American Express, and Discover cards while the AU supports payments via MasterCard, Visa, American Express and EFTPOS.
  • Only on iPhone devices that have a passcode enabled

Make sure that you use correct credentials when setting up your Merchant Account in Adyen to work with NewStore. Ensure that the web services user for your business has the correct roles, permissions, and credentials for each Merchant Account or on a global level. This includes the POS Terminal Management API role for each specific web service user.

The retailer must also ensure that the Authentication Client Key is defined for the web services user that is used for the NewStore and Adyen Integration. There is an informational message in the Adyen customer area stating that is it mandatory to add at least one allowed origin when using a client key. This message can be ignored, an origin is not needed for this configuration. The requirement is to generate the Client Key ONLY.

If any of these items are not configured, users will encounter an “Internal Error” message when attempting a Tap to Pay in iPhone transaction. The retailer needs to work with their Adyen contact to ensure these items are configured properly.

Enabling Tap to Pay on iPhone in Adyen​

Important

These steps must be initiated by your business with the help of the Adyen support team.

To enable Tap to Pay on iPhone in Adyen, create a support request with Adyen with the following details:

  • Request to enable Tap to Pay on iPhone for the specified Merchant Account Name for the retailer within Adyen.

  • Provide a list of stores where Tap to Pay on iPhone will be enabled, and specify which stores are located where, in the US or UK.

    note

    Even if you plan to enable this feature incrementally across stores in your business, request for all US and UK stores to be enabled in the request. Use the Update payment options configuration method to control this feature across specific stores.

  • The payment screen for Tap to Pay on iPhone transactions has text that can be customized. Within the support request to Adyen, specify the custom text that needs to be displayed in this screen. However, on the payment screen, the word Pay is always present, with the custom text appearing after Pay under the shopping cart icon in the payment screen. For example, Pay Dodici for NewStore test transactions.

    note

    The rest of the UI on the screen cannot be changed.

  • Request for the Production URL for the retailer's POS method. You need this URL to configure the NewStore API endpoint to connect to the Adyen backend for the retailer production environment.

    The URL for US stores is available in the Adyen Customer Area, in US data center under Developer > API URL.

    A sample URL is provided here: https://123e7er123101ab1-Merchantname-checkout-live.adyenpayments.com/checkout/possdk/v68

    note

    When updating the NewStore API, ensure that there is no "/" at the end of the URL.

    Important

    For the UK and NL market, the URL endpoint MUST use the EU endpoints for merchant authentication.

    Ensure that you request the EU Tap to Pay on iPhone endpoints and not the US endpoints when requesting to enable the feature for UK and NL locations. The sample URL highlights how the endpoint will change to reflect the correct region and country. It is critical that the retailer uses the correct endpoint for their specific country configuration.

    For the AU market, the URL endpoint MUST use the AU endpoints for merchant authentication.

    Ensure that you request the AU Tap to Pay on iPhone endpoints and not the US endpoints when requesting to enable the feature for AU locations. The sample URL highlights how the endpoint will change to reflect the correct region and country. It is critical that the retailer uses the correct endpoint for their specific country configuration.

    https://987a5as987901ab1-Merchantname-checkout-live.adyenpayments.com/checkout/possdk/v68

You can start Enabling Tap to Pay on iPhone in Adyen after Adyen confirms that the feature has been enabled on their side.

Enabling Tap to Pay on iPhone in NewStore​

You can start enabling Tap to Pay on iPhone by enabling it in Associate App, preparing the devices in the stores for accepting payments, and validating the payment transactions in the app and in NewStore Omnichannel Manager.

Enabling Tap to Pay on iPhone in Associate App​

To enable Associate App to use Tap to Pay on iPhone, first set up the Adyen configuration at NewStore, and configure the related payment option via configuration APIs.

  1. Use the Update PSP Adyen configuration method and add the production URL received from Adyen as the value for the sdk_api_endpoint property.

    note

    We recommend that first, you enable Tap to Pay on iPhone at the top-level for your business and next, configure the payment option for a specific store. You can use the Update payment options configuration method to enable or disable this payment option for specific stores.

  2. Use the Update payment options configuration method and add adyen_pos as a payment option in store_mapping > payment_options for each store_id where you want to enable Tap to Pay on iPhone.

    note

    Currently Tap to Pay is only available in stores in the US, UK, NL and AU.

  3. Verify that Associate App displays the Tap to Pay payment option during checkout for the stores where you have enabled the payment option. See Choosing a payment option .

Preparing iPhones to use Tap to Pay​

The following sections describe the necessary steps to set up Tap to Pay on iPhones:

  • Accepting initial terms and conditions (once per country).
  • Processing Tap to Pay transactions.

Accepting initial terms and conditions​

Before launching Tap to Pay on iPhone in a new region, you must first accept the Apple Terms and Conditions (T&Cs) of that region. The following steps describe how to accept the T&Cs for a country. Perform the steps for every country where you will be launching stores, one time for each.

  1. Before accepting T&Cs, ensure the following:

    • Ensure that Tap to Pay on iPhone has been configured for the store beforehand. See Enabling Tap to Pay on iPhone in Associate App .

    • Ensure that the associate or store personnel preparing the iPhone has an Apple ID, which is associated to an email address that ties in with the merchant account.

      Important

      This Apple ID cannot be part of the Apple Business Account for the retailer. Use a separate Apple ID. If you do not have an Apple ID that is not part of the Apple Business Account, create an Apple ID with a separate email account.

    • Ensure that the associate or store personnel preparing the iPhone is assigned to the store where Tap to Pay on iPhone needs to be accepted. The location of the assigned store will define which country's T&Cs you are accepting.

  2. Log into iCloud on the iPhone being used for the configuration with that specific Apple ID.

  3. Log into the Associate App.

  4. Create a cart with a product and select Tap to Pay > Proceed.

  5. On the Apple Terms and Conditions screen, accept the Apple Tap to Pay Terms and Conditions.

  6. An initialization screen appears and completes the setup to accept payments with Tap to Pay on iPhone.

  7. Now that the T&Cs have been accepted, you may cancel the transaction or complete the transaction if so desired.

note

Once the Apple T&Cs have been accepted, the Apple ID that was used can log out of the iCloud account. The iCloud session is no longer needed and the prompt to accept the T&Cs will no longer be displayed.

Initializing iPhones to accept Tap to Pay transactions​

Each iPhone to accept Tap to Pay transactions must complete an initialization setup. Perform this step on each iPhone that will be used. There is no need to have an Apple ID logged into iCloud for accepting transactions, that was only required for T&C acceptance step.

  1. Before following the initialization process on an iPhone, verify the following:

    • Ensure that Tap to Pay on iPhone has been configured for the store beforehand. See Enabling Tap to Pay on iPhone in Associate App .
    • Ensure that the associate or store personnel preparing the iPhone is assigned to the store where Tap to Pay on iPhone needs to be accepted.

  2. Log into the Associate App.

  3. Create a cart with a product and select Tap to Pay > Proceed.

  4. The first time an iPhone attempts to process a Tap to Pay transaction, the user will be presented with an initialization screen which counts up from 0 to 100. This screen is presented any time the backend Apple application or the NewStore Associate App has been updated. The initialization screen will only appear for the first transaction and will not display on subsequent transactions.

  5. Once the setup and initialization of the software completes, transactions will process normally. When users select the Tap to Pay payment option within the Associate App, they will briefly see an "Initiating Transaction" message followed by the prompt to collect payment.

  6. Hold a credit card, digital wallet or device that supports Tap to Pay on iPhone payments against the top of the iPhone. For a list of supported payment devices, see Pre-requisites .

  7. Wait for the payment to be processed, and complete the checkout.

Validating payment transactions​

Important

Test payment transactions on Tap to Pay on iPhone can only be done in your production environment. You cannot test these payment transactions in your staging environment.

To test a payment transaction, follow the same process as described here to complete checkout for an order in Associate App with the Tap to Pay on iPhone payment method.

When the payment is completed:

  1. The payment status for the order in NewStore Omnichannel Manager is updated to Captured and the origin of the payment is displayed as apple_tap_to_pay. See Monitoring orders .

  2. Go to Adyen Customer Area and verify that the payment transaction has been processed in Adyen.

Handling payment transactions in the UK​

Important

The UK Market leverages Offline PIN as a Cardholder Verification Method (CVM). This CVM method is most commonly used with physical cards issued in the UK, and does not apply to or affect digital wallet payments such as Apple Pay.

How is Offline PIN CVM handled with a payment terminal?

In Offline PIN CVM, the PIN is validated by the physical card. When a payment terminal is used, the shopper must insert their card into the payment terminal and manually enter the PIN.

How is Offline PIN CVM handled with Tap to Pay on iPhone?

When Tap to Pay on iPhone is used for accepting payments, there is no requirement to insert the physical card for cardholder verification. When a customer uses a card for a Tap to Pay on iPhone transaction, which requires Offline PIN, the associate and customer will see the following message on the iPhone: Try a different card.

What should the associate and customer do when the Try a different card message is displayed during a Tap to Pay on iPhone transaction?

The associate should ask the customer if they have another contactless option for payment (such as a digital wallet, or another physical card). If the customer does not have an alternative contactless payment method, the associate must cancel the Tap to Pay on iPhone transaction, and complete the checkout process using an alternate in-store payment method that is available via Associate App, such as via a physical payment terminal or via NewStore Checkout.

Why would a payment transaction require Offline PIN CVM?

In general, a contactless payment transaction will prompt an Offline PIN CVM in one of 2 cases:

  1. When the payment transaction amount is above the specified CVM limit. The CVM limit depends upon the payment method. For example, for Mastercard and Visa transactions, the CVM limit is set as GBP 100. So for every Mastercard and Visa transaction that is over the GBP 100 limit, a PIN will be required and the associate should either use a payment terminal, or request another form of contactless payment from the customer.

  2. When the card being used for the transaction has reached the maximum number of contactless transactions, it can schedule the current transaction for processing in queue. For example, if the card issuer has a maximum counter set to 5 contactless transactions, the sixth contactless transaction on that card will require an Offline PIN (even if the transaction amount is below the CVM limit). There is no standard value for the transaction counter, and varies based on the issuer of the card. The message on the Associate App also displays the same Try a Different Card error message.

    See this table for more details on CVM limits:

    CountryMastercard Contactless LimitVisa Contactless LimitAmex Contactless LimitDiscover Contactless Limit
    UKGBP 100GBP 100GBP 100GBP 100

Handling of international cards within the US​

With Associate App v.1.36.0 or later, Tap to Pay on iPhone has been enhanced to support offline PIN entry for customers who want to use their international credit cards (which often require a PIN entry for payment transactions). This new feature enables retailers to expand the use cases and payment options used in-store by now supporting their international customers worldwide.

Customers who are using an international credit card can enter the PIN directly in Associate App, when prompted for it during the payment step of the checkout process.

If the PIN entry is successful, the payment is processed successfully and the checkout process is completed. If PIN entry fails, the app displays an error message stating Declined - Incorrect PIN. The customer can then re-enter their PIN. If PIN entry is unsuccessful again, the associate can cancel the payment part of the transaction and select a new payment method for the customer Associate App.

Related topics