From 2507249f6e123d3c5bb48d76a6171054f2a6c6f9 Mon Sep 17 00:00:00 2001 From: Jade Burton Date: Thu, 10 Sep 2026 18:39:13 +0200 Subject: [PATCH 1/2] Fix typos etc --- .../docs/terminal-payments/sdks/ios-sdk.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/docs/terminal-payments/sdks/ios-sdk.mdx b/src/content/docs/terminal-payments/sdks/ios-sdk.mdx index 97ab5779..ff874e4b 100644 --- a/src/content/docs/terminal-payments/sdks/ios-sdk.mdx +++ b/src/content/docs/terminal-payments/sdks/ios-sdk.mdx @@ -11,7 +11,7 @@ import Image from '@components/content/Image.astro'; SumUp provides a [native iOS SDK](https://github.com/sumup/sumup-ios-sdk) that enables you to integrate SumUp's proprietary card terminal(s) and its payment platform to accept credit and debit card payments -(incl. VISA, MasterCard, American Express and more) as well as Tap-to-Pay payments on iPhones. SumUp's SDK communicates transparently +(incl. VISA, MasterCard, American Express and more) as well as Tap to Pay on iPhone payments. SumUp's SDK communicates transparently to the card terminal(s) via Bluetooth. Upon initiating a checkout, the SDK guides your user using appropriate screens through each step of the payment process. As part of the process, SumUp also provides the card terminal setup screen, along with the @@ -107,7 +107,7 @@ If you want to dive straight into implementation, carry out the following steps: 6. [Allow the user to select a card reader](#present-card-reader-settings). 7. Finally, [implement the full checkout](#implement-full-checkout). -### Tap-to-Pay Flow +### Tap to Pay Flow Please consider the following when building Tap-to-Pay solutions, as Apple reviews them with high scrutiny: @@ -118,7 +118,7 @@ Please consider the following when building Tap-to-Pay solutions, as Apple revie 2. [Import the SDK into your project file](#importing-sdk). 3. [Initialize the SDK with an Affiliate Key](#initialization). 4. [Log the user in](#logging-the-user-in). -5. Follow steps under [Implementing Tap-to-Pay](#implementing-tap-to-pay). +5. Follow steps under [Implementing Tap to Pay](#implementing-tap-to-pay). ## Integrating iOS SDK @@ -1435,7 +1435,7 @@ open class func presentTapToPayActivation(from fromViewController: UIViewControl * * Call `checkTapToPayAvailability:` before calling this method to find out if this payment method is available * and if activation is needed. - *ń + * * The merchant must be logged in before you call this method. * * Tap to Pay on iPhone requirements: @@ -1469,7 +1469,7 @@ open class func presentTapToPayActivation(from fromViewController: UIViewControl ```swift let productName = SumUpSDK.tapToPayProductName() -// e.g. "Tap To Pay on iPhone" +// e.g. "Tap to Pay on iPhone" ``` @@ -1477,7 +1477,7 @@ let productName = SumUpSDK.tapToPayProductName() ```objc NSString *productName = [SMPSumUpSDK tapToPayProductName]; -// e.g. @"Tap To Pay on iPhone" +// e.g. @"Tap to Pay on iPhone" ``` @@ -1578,7 +1578,7 @@ To run it, clone the [repository](https://github.com/sumup/sumup-ios-sdk) and op ## Known Issues -* In Tap-to-Pay solutions, if entitlements are not correctly set up in your app, `presentTapToPayActivation` may show an error Alert with `Failed to show Terms of Service`. +* In Tap to Pay on iPhone solutions, if entitlements are not correctly set up in your app, `presentTapToPayActivation` may show an error Alert with `Failed to show Terms of Service`. * Businesses using SumUp sub-accounts must first activate the feature on their main account before using it on devices logged in with sub-accounts, otherwise an error message will appear during activation for the sub-account user. ## Community From c5d34d266826d95db5d2eb5c76c912af1bb519b0 Mon Sep 17 00:00:00 2001 From: Jade Burton Date: Thu, 10 Sep 2026 18:39:42 +0200 Subject: [PATCH 2/2] Clarify requirements for integrators relating to Tap to Pay --- .../docs/terminal-payments/sdks/ios-sdk.mdx | 90 ++++++++++++++++--- 1 file changed, 77 insertions(+), 13 deletions(-) diff --git a/src/content/docs/terminal-payments/sdks/ios-sdk.mdx b/src/content/docs/terminal-payments/sdks/ios-sdk.mdx index ff874e4b..77390f0c 100644 --- a/src/content/docs/terminal-payments/sdks/ios-sdk.mdx +++ b/src/content/docs/terminal-payments/sdks/ios-sdk.mdx @@ -109,10 +109,7 @@ If you want to dive straight into implementation, carry out the following steps: ### Tap to Pay Flow -Please consider the following when building Tap-to-Pay solutions, as Apple reviews them with high scrutiny: - -* Follow the [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/tap-to-pay-on-iphone) to save time when Apple reviews your app. -* Also consider [Apple’s marketing guidelines](https://developer.apple.com/tap-to-pay/marketing-guidelines/) and use standard assets where possible. +Apple reviews Tap to Pay on iPhone apps with high scrutiny, and the entitlement must be granted before you can build. Read [Apple's Requirements for Tap to Pay on iPhone](#apples-requirements-for-tap-to-pay-on-iphone) before you start, so that you do not discover a blocking requirement at submission time. 1. [Install the SDK](#adding-sdk-framework-to-project). 2. [Import the SDK into your project file](#importing-sdk). @@ -646,7 +643,7 @@ The returned `SMPReaderStatus` object exposes: - `batteryLevel` — last reported battery level (updated during pairing or transaction processing; freshness varies with reader usage). - `serialNumber` — the serial number printed on the back of the physical reader. -- `readerType` — the reader model (`SMPReaderType` / `ReaderType`): Air, Air Lite, 3G, Solo, Solo Lite. +- `readerType` — the reader model (`SMPReaderType` / `ReaderType`): Unknown, Pin Plus (incl. Pin Plus Contactless), 3G, Air (incl. Air Lite), Solo, Solo Lite. Returns Unknown if no reader has ever been connected, which is the expected value for Tap to Pay on iPhone-only integrations. - `isActive` — `YES` when the reader is currently active or becoming active (e.g. after calling `prepareForCheckout:`). Returns `NO` if no reader has been connected or the saved reader is currently disconnected. @@ -1271,14 +1268,70 @@ SDK 6.0 and earlier presented two screens during the checkout that prompted the When `SMPProcessAsCredit` is used, you should obtain the number of installments from the customer using your own UI. Assign the positive, non-zero value to `numberOfInstallments` on `SMPCheckoutRequest`. -### Implementing Tap-to-Pay +### Apple's Requirements for Tap to Pay on iPhone + +Apple reviews Tap to Pay on iPhone apps with more scrutiny than an ordinary App Store submission. Most delays are caused by requirements that are easy to overlook rather than by defects in the +payment flow itself, so read this section before you submit. + +SumUp does not approve Tap to Pay on iPhone apps — approval comes solely from Apple's review team, and every requirement below is Apple's. SumUp's integration team can help if you get stuck, but the quickest route through review is to satisfy this list first. + +#### Non-Negotiable Requirements + +Each of the following is required. Confirm all of them before submitting. + +* **Hold the entitlement before you build.** Request the Tap to Pay on iPhone entitlement from Apple and wait for approval, then add `com.apple.developer.proximity-reader.payment.acceptance` to your + app. See Apple's guide to [setting up the entitlement](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone?language=objc). Approval is not immediate, so start this early. +* **Follow the [Human Interface Guidelines for Tap to Pay on iPhone](https://developer.apple.com/design/human-interface-guidelines/tap-to-pay-on-iphone).** These are treated as requirements during review, not as suggestions. +* **Follow [Apple's Tap to Pay marketing guidelines](https://developer.apple.com/tap-to-pay/marketing-guidelines/)** and use Apple's standard assets wherever they are offered. +* **Never alter the product name.** Call `tapToPayProductName` rather than hardcoding a string. It returns the correctly localized name for every language the SDK supports, and it tracks any rebranding by Apple. +* **Never draw your own version of Apple's payment UI.** The card-reading and PIN entry screens belong to Apple, as described in the next section. Reimplementing, overlaying, restyling or obscuring them will fail review. +* **Use a runtime availability check, not a hardcoded one.** Requirements move over time, so call `checkTapToPayAvailability` instead of comparing against a fixed iOS version or device list. + +#### What the SDK Provides and What You Must Build + +Apple's review checklist covers the whole merchant experience, but the SumUp iOS SDK already implements most of it. Use the table below to work out which items are yours. + +| Requirement | Provided by the SDK | What you need to do | +| --- | --- | --- | +| Apple terms and conditions | Yes. Activation presents Apple's account-linking sheet, and if the merchant has not yet accepted, the SDK presents it again during a checkout and retries the transaction. | Nothing. Do not build your own terms screen. | +| Merchant authorization | Partly. The SDK blocks activation on employee (sub-account) logins and explains that the main account owner must enable the feature first. | Make sure the merchant signing in is the account owner during first-time setup. | +| Unsupported device and iOS messaging | Yes. Activation shows an alert when the device model, iOS version or Apple's own service does not meet the requirements. | Call `checkTapToPayAvailability` before you offer the feature so merchants never reach a dead end, and hide the entry point when it returns unavailable. | +| Live activation-status checks | Yes. `checkTapToPayAvailability` reports both availability and whether activation has already been completed, checked against Apple rather than cached indefinitely. | Re-check on launch instead of persisting the result. Handle error 101 by running activation and retrying. | +| Initial configuration progress | Yes. The SDK shows a progress screen while the device is prepared, which can take 45 seconds or longer on first use. | Nothing, but do not put your own blocking UI on top of it. | +| Initializing and processing screens | Yes. The SDK's checkout screen moves through initializing, processing and finalizing states. | Nothing. | +| Card-reading | Presented by Apple, not by SumUp. | Nothing, and nothing is possible — the SDK cannot alter or inspect this UI. | +| PIN entry | Presented by Apple, and requested by SumUp's backend when a transaction needs it. | Nothing. Do not build a PIN pad. | +| Approved and declined outcomes | Yes. The SDK presents the outcome screen, with messaging supplied by SumUp's backend. | Read `SMPCheckoutResult` in your completion handler and update your own order state. | +| Timeout outcomes | Handled as a declined payment. There is no separate timeout screen. | Treat a timeout as a failed transaction rather than expecting a distinct result. | +| Merchant education | Yes. Activation includes an introduction to the feature that shows the merchant how to take a payment. | Nothing. Calling `presentTapToPayActivation` again re-shows it, which is useful for a "How it works" menu item. | +| Digital receipts | Not part of the SDK. | Issue receipts through the [Receipts API](/api/receipts/get/). | + +#### Common Issues + +These account for most of the time integrators lose during review and integration. + +* **Testing on the Simulator.** Tap to Pay on iPhone is compiled out for the Simulator and can never work there. Test on a physical iPhone XS or later. +* **Testing with a Sandbox Apple ID.** Debugging requires a non-Sandbox Apple ID, because a Sandbox Apple ID expects both Apple and SumUp to be running against test backends, which the SDK does not + support. Use a [SumUp sandbox merchant account](#sandbox-merchant-account) to avoid moving real money instead. +* **Submitting before the entitlement is granted.** If the entitlement is missing or misconfigured, `presentTapToPayActivation` fails with a misleading `Failed to show Terms of Service` alert. The + cause is the entitlement, not the terms. +* **Activating on an employee account.** A business using SumUp sub-accounts must enable the feature on the main account first, otherwise activation fails for every sub-account. +* **Assuming a passcode is set.** Apple requires a device passcode. Without one, activation fails with a requirements error rather than a passcode-specific one. +* **Starting a payment during a phone call.** Apple blocks card reads while a call is active, which surfaces as a checkout failure. +* **Hardcoding the minimum iOS version.** The floor rises over time. Handle errors 103, 104 and 105 and re-check availability later, since a merchant who updates their device can become eligible. +* **Calling `prepareForCheckout` for a Tap to Pay payment.** It exists to wake a Bluetooth reader and is unnecessary here. See [Differences from Card Reader Checkouts](#differences-from-card-reader-checkouts). +* **Using `SMPProcessAsPromptUser`.** It is not supported for Tap to Pay on iPhone and produces an error. See [Credit/Debit Selection](#creditdebit-selection-processas-property). +* **Building against an old SDK.** Submit with the latest released version of the SDK, and check the [SDK changelog](https://github.com/sumup/sumup-ios-sdk/blob/master/CHANGELOG.md) before you build. + +### Implementing Tap to Pay With Tap to Pay on iPhone merchants can accept contactless card payments on their iPhone without needing a card reader. To add Tap to Pay on iPhone to your app: * Request the Tap to Pay on iPhone entitlement from Apple, receive approval, and then add the `com.apple.developer.proximity-reader.payment.acceptance` entitlement to your app. [Setting up the entitlement](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone?language=objc). -* This feature requires an iPhone XS or later, running iOS 16.4 (iOS 16.7 starting July 8th) or later (ideally 17.5 or later.) The feature does not work on iPad. +* This feature requires an iPhone XS or later and does not work on iPad. The minimum iOS version is raised over time, so treat it as a moving target: as of September 2026 it is **iOS 18.7**. Do not hardcode a version check — call `checkTapToPayAvailability` and handle `SMPSumUpSDKErrorTapToPayiOSVersionTooOld` (104) and `SMPSumUpSDKErrorTapToPayMinHardwareNotMet` (103) instead, so your app keeps working as the floor moves. +* The SDK's own deployment target is iOS 16.0, which is significantly lower than the Tap to Pay on iPhone minimum. An app that builds against iOS 16.0 must therefore gate Tap to Pay on iPhone at runtime rather than assuming it is available. * For debugging and testing you will need to be logged into an iPhone with a non-Sandbox Apple ID. Using a Sandbox Apple ID requires both Apple and SumUp implementations to connect to their respective non-production (test) backends, which the SDK does not support. * **During testing use a SumUp sandbox merchant account**, to avoid transactions going to the acquirer and transferring real money. @@ -1294,7 +1347,13 @@ In your code: * If the feature is not available, your app could, as an example, hide or disable a button or menu item representing the Tap to Pay on iPhone payment method. * The feature is generally available when the following criteria are fulfilled: * the iPhone model and iOS version requirements are met - * the user logs in with a SumUp account registered in one of the countries where SumUp supports Tap to Pay on iPhone (temporarily with exception of Brazil) + * the user logs in with a SumUp account registered in a country where SumUp supports Tap to Pay on iPhone (temporarily with exception of Brazil) + +:::note +Availability is determined at runtime by SumUp, not by a list you can check at build time, so treat `checkTapToPayAvailability` as the only source of truth. In Chile the feature additionally requires iOS 18 or later, which is higher than the general minimum. + +Which card schemes are accepted, and whether a given payment requires PIN entry, also depend on the merchant's country and are applied by SumUp when the transaction is processed. Your app does not configure either of them, and the PIN screen is presented by Apple when one is needed. The SDK does not fall back to another payment method, so treat a failed Tap to Pay on iPhone payment like any other declined payment and decide in your own UI what to offer next. +::: #### Perform Activation If Needed @@ -1370,7 +1429,8 @@ open class func checkTapToPayAvailability() async throws -> (Bool, Bool) * - The hosting app must have the `com.apple.developer.proximity-reader.payment.acceptance` * entitlement. * - * - The merchant must have an iPhone XS or later with iOS 16.4 or later (iOS 17 or later recommended.) + * - The merchant must have a supported iPhone model running a supported iOS version. + * See the requirements above, as the minimum iOS version changes over time. * The feature does not work with iPads. * * @param fromViewController The UIViewController instance from which the UI should be presented modally. @@ -1393,7 +1453,8 @@ open class func presentTapToPayActivation(from fromViewController: UIViewControl * - The hosting app must have the `com.apple.developer.proximity-reader.payment.acceptance` * entitlement. * - * - The merchant must have an iPhone XS or later with iOS 16.4 or later (iOS 17 or later recommended.) + * - The merchant must have a supported iPhone model running a supported iOS version. + * See the requirements above, as the minimum iOS version changes over time. * The feature does not work with iPads. * * @param fromViewController The UIViewController instance from which the UI should be presented modally. @@ -1443,7 +1504,8 @@ open class func presentTapToPayActivation(from fromViewController: UIViewControl * - The hosting app must have the `com.apple.developer.proximity-reader.payment.acceptance` * entitlement. * - * - The merchant must have an iPhone XS or later with iOS 16.4 or later (iOS 17 or later recommended.) + * - The merchant must have a supported iPhone model running a supported iOS version. + * See the requirements above, as the minimum iOS version changes over time. * The feature does not work with iPads. * * @param fromViewController The UIViewController instance from which the UI should be presented modally. @@ -1462,7 +1524,7 @@ open class func presentTapToPayActivation(from fromViewController: UIViewControl #### Product Name -`tapToPayProductName` returns the localized "Tap To Pay on iPhone" string. It is localized in all languages supported by the SDK and exposed as a convenience for use in your app's UI — use it instead of hardcoding the product name, as Apple may update the branding. +`tapToPayProductName` returns the localized "Tap to Pay on iPhone" string. It is localized in all languages supported by the SDK and exposed as a convenience for use in your app's UI — use it instead of hardcoding the product name, as Apple may update the branding. @@ -1562,7 +1624,7 @@ The SDK uses Objective C header files, but XCode can also display its public typ | SMPCurrencyCodes.h | Defines available currency codes | | SMPMerchant.h (Merchant) | Describes a Merchant, including Merchant Code (identifier) and currency used by merchant | | SMPReaderStatus.h | Reader information: battery level, serial number, model type, and active state | -| SMPReaderType.h (ReaderType) | Enumeration of card reader models: Pin Plus, 3G, Air, Solo, Solo Lite | +| SMPReaderType.h (ReaderType) | Enumeration of card reader models: Unknown, Pin Plus, 3G, Air, Solo, Solo Lite | | SMPOfflineSessionDetails.h | Offline session state: remaining time, transaction counts, total approved amount | | SMPSkipScreenOptions.h (SkipScreenOptions) | Describes options allowing to skip transaction confirmation screen | | SumUpSDK.h | Declares project version | @@ -1581,6 +1643,8 @@ To run it, clone the [repository](https://github.com/sumup/sumup-ios-sdk) and op * In Tap to Pay on iPhone solutions, if entitlements are not correctly set up in your app, `presentTapToPayActivation` may show an error Alert with `Failed to show Terms of Service`. * Businesses using SumUp sub-accounts must first activate the feature on their main account before using it on devices logged in with sub-accounts, otherwise an error message will appear during activation for the sub-account user. +For the wider set of issues integrators hit with Tap to Pay on iPhone, see [Common Issues](#common-issues). + ## Community Got questions or found a bug? Get in contact with our integration team through the [contact form](/contact).