docs: clarify Apple's requirements for Tap to Pay on iPhone in the iOS SDK guide - #968
Draft
jadeburton-sumup wants to merge 4 commits into
Draft
docs: clarify Apple's requirements for Tap to Pay on iPhone in the iOS SDK guide#968jadeburton-sumup wants to merge 4 commits into
jadeburton-sumup wants to merge 4 commits into
Conversation
Corrects factual errors in the iOS SDK guide, verified against the SumUpSDK 7.1.2 headers and resource bundle: - Remove a stray character that had corrupted an Objective-C doc comment. - Use "Tap to Pay on iPhone" rather than "Tap To Pay on iPhone". The SDK's localized string returns the lowercase form; the capitalised spelling came from an incorrect comment in SMPSumUpSDK.h. - Drop the "Tap-to-Pay" hyphenation in favour of Apple's "Tap to Pay on iPhone" branding, which the page already links out to. Heading slugs are unchanged, so existing anchors still resolve. - Replace the stale minimum iOS version. The page claimed 16.4, with an undated "iOS 16.7 starting July 8th" note and a conflicting 17.5 recommendation. The minimum rises over time and is currently 18.7, so the requirement is now dated and points at the runtime checks instead of a hardcoded version. The same stale figures are removed from three reproduced SDK header comments. - Correct both SMPReaderType listings, which each omitted a case and neither of which mentioned Unknown, the value returned when no physical reader has been connected.
The guide explained how to check availability and run activation, but stopped before the checkout itself, and never documented SMPPaymentMethod. The Tap to Pay case was therefore not discoverable from the docs, leaving the flow impossible to complete without reading the SDK headers. - Document the SMPPaymentMethod cases where paymentMethod is introduced. - Add a Tap to Pay checkout example in Swift and Objective-C. - Add a table for error codes 100-105 describing what an app should do for each, and noting that the hardware, iOS version and requirement failures can clear if the merchant updates their device. - Describe how Tap to Pay differs from card reader checkouts: lastReaderStatus stays nil, readerType is Unknown, Tip on Card Reader is unavailable so tips must be set programmatically, and prepareForCheckout is unnecessary and reports error 60 for a Tap to Pay-only integration. - Note that the sample app does not implement Tap to Pay. Its settings screen has a disabled toggle that is not wired to the SDK, so it is not a usable reference for this flow.
Integrators lose time in review cycles with Apple because the guide did not say which of Apple's checklist items the SDK already satisfies. The only guidance was two links to the Human Interface and marketing guidelines, so integrators had to infer the split by reading the headers, and several asked SumUp directly instead. Add an "Apple's Requirements for Tap to Pay on iPhone" section covering: - Non-negotiable requirements, including that the entitlement must be granted before building, that the product name must come from tapToPayProductName, and that availability must be checked at runtime rather than against a hardcoded iOS version. - A table mapping each checklist area to whether the SDK provides it. Terms and conditions, activation status, configuration progress, initializing/processing screens, outcomes and merchant education are handled by the SDK. The card-reading and PIN screens belong to Apple and cannot be altered. Receipts are out of scope and come from the API. - A note that the SDK does not use ProximityReaderDiscovery and exposes no way to invoke it, so apps should not claim to present it in review notes. - Common mistakes: Simulator testing, Sandbox Apple IDs, submitting before the entitlement is granted, activating on an employee account, missing device passcode, starting a payment during a call, and calling prepareForCheckout or SMPProcessAsPromptUser for Tap to Pay. Also state that approval comes from Apple alone rather than SumUp, note that availability is resolved at runtime rather than from a published country list, record Chile's higher iOS 18 floor, and point Known Issues at the new section instead of repeating it.
Integrators ask which card schemes, PIN requirements and fallback behaviour apply to their launch markets. The answer is that none of them are theirs to configure, but the guide did not say so, leaving the question open for each new integration. Note that accepted schemes and whether a payment needs PIN entry are determined by the merchant's country and applied by SumUp at processing time, that Apple presents the PIN screen, and that the SDK has no fallback to another payment method, so a failed Tap to Pay payment should be handled like any other decline. No scheme list is given, as the accepted schemes vary by country.
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
developer-sumup-com | 7f4ef4c | Commit Preview URL Branch Preview URL |
Sep 09 2026, 09:08 AM |
matoous
approved these changes
Sep 9, 2026
jadeburton-sumup
marked this pull request as draft
September 9, 2026 09:33
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes TOP-1706.
Why
SDK integrators lose time in review cycles with Apple because the iOS SDK guide never said which of Apple's checklist items the SDK already satisfies. The only guidance was two links, to the Human Interface and marketing guidelines, so integrators had to infer the split by reading the SDK headers — and several asked SumUp directly instead. One such request is quoted on the ticket.
The guide also stopped short of the Tap to Pay checkout itself and never documented
SMPPaymentMethod, so the flow could not be completed from the docs alone.What changed
All changes are in
src/content/docs/terminal-payments/sdks/ios-sdk.mdx.Factual corrections (
bcbec27) — verified against the SumUpSDK 7.1.2 headers and resource bundle:SMPReaderTypelistings, which each omitted a case and neither of which mentionedUnknown.Tap to Pay checkout documentation (
1723c29):SMPPaymentMethodand added a checkout example in Swift and Objective-C.lastReaderStatus, tipping,prepareForCheckout, reader settings).Apple's requirements (
44008e7) — the substance of the ticket:Country-dependent behaviour (
7f4ef4c):Two corrections worth reviewer attention
These are approval-critical, and both contradict what an integrator would reasonably have assumed from the old page:
ProximityReaderDiscovery. It exists inios-sumup-tapsource but is gated behind#available(iOS 26.0, *)and post-dates the shipped build; it is absent from the 7.1.2 binary. An app claiming to present it in its review notes would be making a false statement to Apple.Also worth noting: there is no distinct timeout outcome.
pinEntryTimeoutis mapped into the declined path, so the docs describe it that way rather than implying a third result.Deliberate omissions
Confirmed with the ticket owner:
checkTapToPayAvailabilityas the only source of truth. Chile's higher iOS 18 floor is recorded, as it is a hardcoded rule.Verification
npm run check— passes. One pre-existing error insrc/components/Forms/CopyInput/CopyInput.tsx(@sumup-oss/iconshas no exported memberCopy) is present onmainand untouched by this branch.npm run build— passes.npm run lint:markdown— no issues across 150 files.npm run linkcheck— all internal links valid, including the new anchors; 4384 links checked across rendered pages.Follow-up, not for this PR
PaymentCardReaderWrapper.swift:32inios-sumup-tapsetsrecommendedMinimumiOSVersion = "18.6"with the comment "18.6 will be blocked in July 2026". That date has passed. If 18.7 is the current floor, the in-app OS alert is telling merchants on 18.6 that they are supported when they are not. That needs a code change in the SDK, not a docs change.