Merchant Education
What merchants and their staff need to know to take payments with Tap to Pay, what your app has to teach them, and the questions they ask most. Use this page to build your in-app education, your help center, and your support answers.
This page is written for the team building the app. It collects the guidance Koard gives integrators most often. The wording in the tables is plain enough to reuse with merchants.
What Your App Must Teach
| Platform | Requirement | How to meet it |
|---|---|---|
| iPhone | Apple requires education inside the app. A merchant sees it after accepting Apple's terms, and can open it again later from Settings or Help. | On iOS 18 and later, call KoardMerchantSDK.shared.presentTutorial(from:), which presents Apple's own screens, including PIN entry and accessibility. For earlier iOS versions, present the same content with your own screens built from Apple's Marketing Guide and Toolkit. See Going to Production on iOS. |
| Android | The platform provides no education screens. | Build your own from the sections below and make them reachable from Settings or Help. See Going to Production on Android. |
Training sessions, emailed videos, and printed guides are useful, but on iPhone they do not replace education inside the app.
On iPhone, Apple's review checks that education appears right after the merchant accepts the terms, can be reopened from Settings or Help, shows how to accept contactless cards and digital wallets, and uses Apple's approved images and wording. Do not tell merchants they can skip it.
Your screens can look however you like, with one exception. On iPhone, the screen shown while the customer taps belongs to Apple and cannot be changed. On Android, your app draws that screen, so the tap instructions on it are yours to write.
When to Show It
Start before the merchant's first payment attempt, not during it.
- The merchant opens the part of your app that takes payments.
- Your app checks whether Tap to Pay is set up for this merchant and device.
- If it is not, your app shows what Tap to Pay is and how it works.
- The merchant accepts the platform's terms and finishes setup. On iPhone this is Apple's Terms and Conditions. On Android it is device enrollment.
- Your app prepares the reader and shows its state: not ready, preparing, or ready.
For an app that already has merchants, show the introduction the first time each merchant opens the app after you add Tap to Pay. Keep a way to start setup in Settings, because a merchant can dismiss the terms prompt and come back later.
Before the First Payment
A merchant is ready when every item for their platform is true.
| iPhone | Android |
|---|---|
| An iPhone XS or later on the latest iOS version. Tap to Pay on iPhone does not run on iPad. Update in Settings, General, Software Update. | A supported NFC phone or tablet on Android 13 or later. |
| A device passcode is set. | NFC is on, Google Play Protect is on, and date and time are set automatically. |
| The iPhone is signed in with the merchant's Apple Account. | Developer options are off. |
| An admin has accepted Apple's Tap to Pay on iPhone Terms and Conditions. | The Visa Tap to Pay Ready app is installed and up to date. The merchant installs it once and never needs to open it. |
| The merchant has signed in to your app and chosen the location they are taking payments at. | The merchant has signed in to your app, chosen the location, and enrolled the device. |
Apple's terms are accepted once for each merchant. One admin accepts for every user and device of that merchant. Staff who are not admins should see a message telling them to contact their admin.
Your app should check these items and tell the merchant exactly which one is missing. On Android, the SDK's readiness state reports the blocker. On iPhone, reader preparation reports it. An app cannot turn NFC on, so send the merchant to the device settings when it is off.
Taking a Payment
Contactless Cards
- Check that the card shows the contactless symbol on the front or back.
- Enter the amount and start the payment, then present the phone to the customer.
- The customer holds the card in place until the phone confirms the read.
| Platform | Where the customer holds the card |
|---|---|
| iPhone | Flat and horizontal on the tap area shown on the screen, for a few seconds. |
| Android | Flat against the back of the phone, over the upper middle on most models, for one to two seconds. NFC antenna location lists the position by manufacturer. On a tablet, check the manufacturer's specification. |
When a card does not read, the card or its position is the usual cause:
- Take the card out of a wallet or sleeve. Other cards and shielding interfere.
- Move the card slowly around the tap area until the phone reacts, then hold it still.
- Remove a thick or metal phone case.
- Try another contactless card or a digital wallet. Plastic cards read less reliably than wallets on some Android phones.
Phones, Watches, and Digital Wallets
Apple Pay, Google Pay, other digital wallets, and contactless wearables work the same way as a card. The customer holds their device near the tap area until the payment completes.
PIN Entry
Some cards ask for a PIN. The customer enters it on the merchant's phone, so the merchant hands the phone over and looks away.
- On iPhone, the customer can choose Accessibility Options on the PIN screen. Spoken instructions guide them to draw each digit or tap once per count, then swipe right with two fingers to submit.
- The PIN is encrypted on the device before it is sent, and your app never sees it. The card issuer checks it during authorization. A wrong PIN is declined by the issuer.
- If a card cannot complete a contactless PIN payment, ask the customer for another contactless card or a digital wallet.
After the Tap
Wait for the result on the screen before handing over goods. A payment is approved, declined, or not completed. Offer a digital receipt once the result is shown, whatever the outcome.
If the app loses its connection and the result never appears, do not charge the customer again straight away. Check the transaction history first. Your app should look up the payment before it allows another attempt, as described in Idempotency.
Do and Do Not During a Payment
Give merchants these rules in your own guide. Start with the rules that apply to every phone, then add the ones for their platform.
| Do | Do not |
|---|---|
| Use a supported phone and operating system, and keep your payment app updated. | Take payments on a rooted phone, or on an Android phone with an unlocked bootloader. |
| Stay connected to the internet. | Switch to another app or lock the phone while a payment is running. |
| Keep the payment app open on the screen until the payment finishes. | Record, mirror, or share the payment screen. |
| Let the customer enter their PIN privately. | Treat a successful tap or a checkmark as approval. Wait for the app's final result. |
| Check a payment's status when it was interrupted or its result is unclear. | Charge again before you have checked. That can charge the customer twice. |
| Offer another way to pay when a card will not work. |
| iPhone only | Android only |
|---|---|
| Keep the device passcode turned on. | Turn NFC on. |
| To lock your iPhone while a customer enters a PIN, turn on Screen Lock for the payment app in Settings. It is optional. When it is on, you unlock with Face ID, Touch ID, or your passcode to continue. | Keep developer options and USB debugging off. |
When you write your own merchant guide, do not promise protections that the platforms do not promise. Apple protects card and PIN information during a payment, but do not state that every screenshot or recording comes out black, that all background apps are frozen, that all overlays are blocked, or that the phone always locks after PIN entry. These behaviors differ between iPhone and Android, and some are optional settings. Apple describes its protections in Tap to Pay on iPhone security.
What Merchants Ask
| Question | Answer |
|---|---|
| Do I need a card reader? | No. The phone is the reader. |
| Which payments can I take? | Contactless cards, phones, and watches. Cards cannot be inserted or swiped. Some contactless cards may not be accepted, and card limits can apply. |
| Do I need an internet connection? | Yes. Every payment is authorized online. |
| Is it secure? | Yes. The PIN is encrypted on the phone and never shown to the merchant or to your app. On iPhone, the card number is protected by the phone's secure chip, your app never sees the full number, and Apple does not store card numbers. |
| Can more than one phone take payments for my business? | Yes. Any number of phones can take payments for the same location. |
| Can I use an iPad? | No. Tap to Pay on iPhone runs on iPhone only. |
| Does each staff member accept Apple's terms? | No. One admin accepts once for the whole business. |
| Why is the first payment slow, or why did it fail? | The phone sets itself up after the first sign-in. Wait until the app shows that the reader is ready. |
| Why was a payment declined? | The card issuer or the processor declined it. Ask the customer for another card or wallet. |
| Can I cancel or refund a payment? | Yes, when your app offers it. Before the day's batch settles, the payment is cancelled with a reversal. After it settles, it is refunded. A refund cannot be more than the original amount, and some refunds ask the customer to tap the card again. |
| Can I add a tip after the payment? | Yes, when your app offers it, until the payment settles. See Tip Adjust. |
| What happens with a surcharge? | The customer sees the surcharge and confirms it. If they decline, or do not answer within two minutes, the payment is cancelled and nothing is held on the card. See Surcharging. |
| When do I get paid? | Payments settle when the day's batch closes, either at a set time or when it is closed by hand. Deposit timing after that comes from the processor. See Batch and Settlements. |
| Why does it say another app is using the reader? | On Android, another payment app on the phone holds the reader. Close that app or wait for it to finish. |
| I changed location. What do I do? | Choose the new location in your app's settings before the next payment. |
Fixes a Merchant Can Try
| Problem | iPhone | Android |
|---|---|---|
| Tap to Pay is not ready | Update iOS, set a device passcode, sign in to the Apple Account, and accept Apple's terms when asked. Then close and reopen the app. | Install or update Visa Tap to Pay Ready, turn on NFC and Google Play Protect, set date and time to automatic, turn off developer options, then restart the phone. |
| A payment will not start | End any phone call, stop screen recording, and charge the phone above 5 percent. Check that the iPhone is signed in with a normal Apple Account, not a sandbox test account. | End any phone call, stop screen recording, and charge the phone above 5 percent. Close other apps that use NFC. |
| A card will not read | Hold the card flat and horizontal on the tap area for a few seconds. Try another contactless card or a wallet. | Hold the card flat against the upper back of the phone, move it toward the camera, and remove a thick case. Close other apps that use NFC. |
| The payment cancels as soon as it starts | Close and reopen the app, then wait for the reader to be ready. | Turn off developer options. If it continues, clear the cache of the Visa Tap to Pay Ready app in the phone's app settings and try again. |
| Setup takes a long time before the first payment | Keep the app open and connected. The app prepares the reader after sign-in. | Keep the app open and connected until enrollment finishes. |
| A payment result never appeared | Check the transaction history before charging again. | Check the transaction history before charging again. |
Developers will find the matching error codes in iOS Troubleshooting and Android Troubleshooting.
When to Contact Support
Merchants contact you first. Show your support contact in the app. Koard takes the issues you cannot resolve: SDK behavior, reader behavior on either platform, certification, and infrastructure.
When you need Koard, write to support@koard.com. If live payments are affected, say so in the subject line. Include:
- The environment, UAT or production.
- The merchant, location, and terminal.
- The transaction ID, and the time of the attempt.
- The phone model, operating system version, and SDK version.
- What the merchant saw, and the error your app received.
Never send card numbers, PINs, API keys, or merchant credentials.
Sources
Apple's instructions for merchants are in How to use Tap to Pay on iPhone, and its checkout guidance is in the Human Interface Guidelines. Apple's version wins if it differs from this page.
