iOS SDK 2.6.0: ready Tap to Pay reader but empty checkout methods, persists after reauthorization

Questions
1

Hello Square Developer Support,

We are investigating an intermittent Tap to Pay failure in our native iOS app. Successful $1 Tap to Pay transactions have previously completed on this test iPhone, but we can now reproduce the following:

  1. Authorize Square with a production seller access token and location.
  2. Check the merchant’s Apple link status; the account is linked. The SDK reports the iPhone Tap to Pay reader ready and contactless input available.
  3. Start an onlineOnly USD 100-cent payment with a new UUID paymentAttemptID, default prompt mode and AdditionalPaymentMethods([.tapToPay]).
  4. Square’s UI displays “Connect hardware to take card payments”. The active PaymentHandle.additionalPaymentMethods is empty.

Diagnostic values before and throughout the failing checkout:

  • SDK version 2.6.0
  • isDeviceCapable=true
  • requested additional-method mask=2; tapToPay.rawValue=2
  • availableCardInputMethods=Contactless
  • reader model=3 (tapToPay), status=4 (ready), unavailable reason=nil
  • active handle additionalPaymentMethods=[]

An initial recording observed this for ten seconds without the method appearing. Successful prior attempts exposed additional method type=4 (tapToPay). We then added a safeguard to cancel an empty, cancelable checkout through PaymentHandle.cancelPayment, finishing through didCancel. The next user-initiated attempt invalidated local authorization reuse, retrieved scoped credentials, and passed through SDK deauthorization/authorization. It again showed the same mismatch. No card was presented in these failed checks.

The application has one SDK initialization in didFinishLaunching and a process-wide operation guard around authorization/setup/payment. We do not force Apple relinking or automatically start a second payment. The test device is an iPhone 15 Pro Max. Additional device/OS diagnostics can be supplied privately to Square staff if needed.

Could you identify why the reader can report ready while the payment handle exposes no Tap to Pay method, and the supported recovery or integration change? Is the additional-method configuration above correct for the default prompt in 2.6.0? Is a further readiness signal required?

Representative diagnostic excerpt (no account identifiers, tokens, or card data):

before checkout: sdk=2.6.0, capable=true, requested=2, tapConstant=2, inputs=Contactless, methods=no active handle, readers=[model=3, status=4, reason=none]
checkout +0s: sdk=2.6.0, capable=true, requested=2, tapConstant=2, inputs=Contactless, methods=[], readers=[model=3, status=4, reason=none]
checkout +3s: sdk=2.6.0, capable=true, requested=2, tapConstant=2, inputs=Contactless, methods=[], readers=[model=3, status=4, reason=none]

The same values persisted for ten seconds in an earlier attempt, and recurred after cancellation and authorization refresh.

3

Hello, @youthrush

I’d try the following:

  • Confirm .tapToPay is passed when creating the payment handle, not only when starting checkout.
  • Test with the latest Square SDK instead of 2.6.0.
  • Don’t repeatedly relink or reauthorize as a workaround. mcdvoice
  • If it still occurs, send Square the handle-creation logs and timestamps.

Best Regard,
James

4

@youthrush - Could you please provide your application ID, merchant token, and a timestamp of when you ran into this issue, ideally within the last two weeks?

5

Hi, thanks for looking into this.

  • Application ID: sq0idp-_0go7RxWoYPZRGj_kvSUjg
  • Merchant ID (merchant token): [redacted] — this is the personal Square account used in our recent donation test, which we believe was also used for the failed attempt.
  • Timestamp: September 21, 2026, 06:07:54–06:07:57 UTC (September 20, 11:07:54–11:07:57 PM PDT).
  • SDK/device: Square Mobile Payments SDK 2.6.0, iPhone 15 Pro Max.

During that attempt, the reader reported ready and contactless input was available, but the payment handle’s additionalPaymentMethods remained empty. Checkout displayed “Connect hardware to take card payments.”

We pass AdditionalPaymentMethods([.tapToPay]) directly in the startPayment call that creates the handle. The issue also recurred after SDK deauthorization and reauthorization. No card was presented during this failed attempt.

Please let us know if you need additional diagnostics or a private channel for further account details.

6

Hi @jseok — we have fresh diagnostics from September 23 that show the issue is intermittent.

On the same iPhone, app build, Square business and location, five of seven checkout attempts offered Tap to Pay; two did not. Successful tests included reaching the actual card-reading screen after fully closing and reopening the app.

All times below are UTC on September 23, 2026:

Checkout started Result
21:55:24 Tap to Pay available
21:57:56 No Tap to Pay method; cancellation confirmed at 21:58:00
22:10:10 Tap to Pay available
22:10:27 Tap to Pay available
22:11:50 Tap to Pay available
22:12:23 No Tap to Pay method; cancellation confirmed at 22:12:26
22:12:29 Tap to Pay available again

During both failures, the SDK reported a ready Tap to Pay reader, contactless input available, and no reader-unavailable reason, but the active payment handle’s additionalPaymentMethods was empty.

Configuration:

  • Square Mobile Payments SDK 2.6.0

  • iPhone 15 Pro Max, iOS 27.2 (24B5084k)

  • App 2.14.0 (69)

  • USD 1.00, online-only processing

  • .tapToPay passed directly in the startPayment prompt parameters

All seven attempts ended in cancellation, with no completed-payment callback. We do not automatically retry payments or force Apple relinking.

Account clarification: These new diagnostics identify the affected merchant conclusively, and it differs from the tentative merchant ID in our previous reply. Please provide a private channel where we can send the verified merchant/location and payment-attempt IDs.

Could your SDK team compare these working and failing sessions and advise on the cause or supported recovery? Please also confirm whether this iOS version has any relevant compatibility limitation. This issue is blocking our release.

8

AdditionalPaymentMethods([.tapToPay]) in the prompt parameters you pass to startPayment is right for the default prompt in 2.6.0. There’s no additional documented readiness API you’re missing, though your integration does need a handle-level check (below). Note also that the docs’ “Create prompt parameters” section lists only keyed and cash — that’s a documentation gap; .tapToPay is valid, and it’s the value behind the mask of 2 you’re logging.

A ready reader can coexist with an empty list. These are two different signals. statusInfo.status == .ready describes the reader; whether Tap to Pay is offered for a given payment is decided separately, at payment-handle creation, based on the Tap to Pay reader’s payment capability being active — which isn’t surfaced through ReaderInfo. So you’re observing one signal while a different, unobservable one gates the prompt.

The key consequence: the handle’s additionalPaymentMethods is fixed when the handle is created and never recalculated. A handle that starts empty stays empty for its whole life, regardless of what the reader does afterward. That’s why the ten-second observation could never have succeeded, and why cancelling and starting a new payment was the only thing that could recover — matching your 22:12:23 failure and 22:12:29 success.

What I’d change:

  1. Check the handle, then restart — don’t wait. After startPayment, look for a .tapToPay entry in the active handle’s additionalPaymentMethods. If it’s missing, cancel and start a new payment. Your existing cancelPayment/didCancel safeguard is the right mechanism; restart instead of polling. Use a short backoff over a couple of attempts — I can’t tell you how long this window lasts, so don’t assume one retry always clears it.
  2. Reauthorizing won’t help. The gate is reader payment-capability state, not authorization, so the deauthorize/reauthorize cycle isn’t addressing it.
  3. Allow settle time before enabling checkout after launch, foregrounding, and any authorization change. Your own note that successes followed fully reopening the app fits this: confirm isDeviceCapable() and a .ready Tap to Pay reader via a ReaderObserver, then give it a moment before a payment can start.

While this explains the mechanism and (hopefully!) gives you a recovery path, I’m not sure why that capability signal is slow to settle on your device. Still looking into that.

If the handle check in (1) doesn’t clear it, let me know!

9

Hi Square team,

We’ve narrowed down a persistent merchant-name mismatch in our iOS Mobile Payments SDK integration and would appreciate your help tracing it.

Environment

  • Square Mobile Payments SDK 2.6.0

  • iPhone 15 Pro Max

  • iOS 27.2 (24B5084k)

  • App version 2.14.0, diagnostic build 84

Our app supports two separate Square accounts: a personal account and an organization account. In personal mode, our server supplies the personal account’s credentials and location ID. Immediately before checkout, the SDK’s authorizationManager.location.id matches that personal location, and its reported name is “Unlocking Prophecy.”

However, the Tap to Pay card-reading screen displays “Pay YES”, which is the organization account’s business name.

Square’s own Point of Sale app, signed into the personal account, displays the correct personal business name. That comparison confirms the displayed name only; we have not confirmed a completed payment in the Square app.

Latest reproduction

  • September 28, 2026, 15:59:34 UTC / 8:59:34 a.m. PDT

  • SDK payment-attempt ID: 25E3CEA7-BBB2-44B8-BA7C-5F37346E6D44

  • Personal mode; $1.00 USD

  • SDK reported the personal location and a ready Tap to Pay reader

  • Reader displayed “Pay YES”

  • Canceled without presenting a card at 16:00:30 UTC

Checks and isolation tests completed

  • Verified through Square’s API that the personal and organization accounts have distinct merchant/location IDs.

  • Verified the personal location’s business name is “Unlocking Prophecy” and the organization location’s business name is “YES.”

  • Restored Square’s default payment prompt instead of directly triggering Tap to Pay through our custom prompt. The mismatch persisted.

  • Disabled automatic SDK preparation at app launch and prepared the personal account explicitly. The mismatch persisted.

  • Restarted the iPhone.

  • Disconnected and reconnected the personal Square connection.

  • Disconnected the organization’s connection, closed/reopened the app, and retried personal checkout. The mismatch persisted.

Our SDK account-switching code awaits deauthorize completion before authorizing a different token/location. We also check the authorized location before starting checkout.

Separate payment failure
Earlier card-present attempts reached the reader but then displayed Square’s “Payment failed. The payment could not be completed. Please try again.” After the user selected Cancel, our delegate received didCancel, without a server payment ID or an exposed didFail error. Neither account showed those transactions; subsequent Payments API queries for that test day returned no payments.

An organization payment completed successfully on September 25 using build 81. The later failures also occurred on build 81, before our diagnostic builds. We have not established whether the wrong reader name and payment failure share a cause.

Could you investigate:

  1. Which merchant/terminal identity and display name were supplied to Tap to Pay for the latest attempt above?

  2. Why that identity could disagree with the personal location reported by authorizationManager?

  3. Whether any SDK reader configuration persists across merchant changes, and the supported way to refresh it?

  4. How we can capture the underlying processing error when Square displays a failure but only reports didCancel after the user dismisses it?

We can provide the application ID, both merchant/location IDs, and reviewed diagnostic logs through a private support channel. Please let us know the appropriate secure destination.

Thank you.

Sincerely,

John

10

Following up after six days—this issue is still blocking our Tap to Pay release. Could someone escalate it to the Mobile Payments SDK engineering team?

In Personal Canvassing, our server credentials and the SDK’s authorized location match the personal Square account, but the reader displays “Pay YES,” the separate organization’s business name.

The mismatch persisted after:

  • Switching to Square’s default payment prompt.

  • Removing automatic background authorization.

  • Restarting and reconnecting the personal account.

  • Disconnecting the organization account entirely.

Earlier card attempts displayed “Payment failed”; neither account received those payments. We have not established whether the incorrect name and payment failure share a cause.

We’re using SDK 2.6.0. A recorded reproduction occurred September 28 at 15:59:34 UTC. We can provide application and merchant identifiers, device details, and diagnostic logs through your preferred secure channel.

Please advise how to verify the merchant identity used by the Tap to Pay reader and retrieve the underlying failure reason. Can you also confirm someone is investigating this?

11

Thank you for your patience we are investigating this further now. I just sent you a DM to collect a bit more account information from you.