Skip to content

Link the merchant's Apple Account

Before an iPhone can accept payments, the merchant must accept Apple's Tap to Pay on iPhone Terms and Conditions. linkAccount() presents Apple's sheet and links the merchant's Apple Account to Tap to Pay on iPhone.

Before you start: the SDK must be initialized, and the device must be signed in to iCloud.

What linking does

  • Linking happens at the iOS system level. Once an Apple Account is linked for a merchant, it stays linked across app launches, and in some cases even across app reinstalls.
  • The Terms must be accepted by a user authorized to bind the merchant, such as an owner or administrator. If a non-admin user reaches this point, tell them to contact their administrator instead of presenting the sheet (Prepare for App Review requires this).
  • Linking requires an iCloud sign-in on the device; otherwise linkAccount() throws .accountLinkingRequiresiCloudSignIn.

Check link status

isAccountLinked() retrieves the merchant's acceptance status from Apple. Don't track it in your own flag or database. Apple's answer is the source of truth, and App Review checks for this. The SDK caches the answer for up to linkStatusCacheDuration (default 300 seconds).

A true result is reliable. A false result can also mean the check failed or the device isn't provisioned yet, so don't treat it as proof the account is unlinked.

When you need a current answer (for example, on a settings screen), bypass the cache with forceRefreshLinkStatus(). clearLinkStatus() drops the cached status so the next isAccountLinked() re-checks with Apple.

Link the account

Check the status first, then link. If the account turns out to be linked already, linkAccount() throws .accountAlreadyLinked. Treat that as success.

accountAlreadyLinked is success

If the merchant already accepted the Terms and Conditions, linkAccount() throws .accountAlreadyLinked. Don't show this to the merchant as a failure. Continue on to Prepare the reader.

Manage or unlink the account

There is no API to unlink an Apple Account from Tap to Pay on iPhone, because the link lives at the iOS system level. clearLinkStatus() and clearAllCaches() only reset the SDK's local caches. They never unlink the account.

Deleting and reinstalling the app usually returns it to an unlinked state, but because the link is system-level it can survive a reinstall (see What linking does). After reinstalling, check with forceRefreshLinkStatus(): true means the link survived. false doesn't guarantee the link is gone, since the check also returns false when it fails or the device isn't provisioned yet. If you need a guaranteed unlinked state (for testing or App Review recordings), use a device and Apple Account pair that has never been linked for the merchant.

Merchants can review the linked account in the Settings app under Wallet & Apple Pay ▸ Tap to Pay on iPhone. iOS doesn't provide a deep link to that screen. The best your app can do is open its own settings and direct the merchant from there.

Next: Prepare the reader.

// Cached for up to linkStatusCacheDuration (default 300 seconds).
let linked = await tapToPay.isAccountLinked()

// Bypass the cache and check with Apple directly:
let refreshed = await tapToPay.forceRefreshLinkStatus()

// Drop the cached status so the next isAccountLinked() re-checks with Apple:
tapToPay.clearLinkStatus()

func enableTapToPay(using tapToPay: FinixTapToPay) async -> Bool {
    if await tapToPay.isAccountLinked() {
        return true
    }
    do {
        try await tapToPay.linkAccount() // Presents Apple's Terms and Conditions
        return true
    } catch TapToPayError.accountAlreadyLinked {
        return true // Already linked at the iOS level, so treat this as success.
    } catch TapToPayError.accountLinkingCancelled {
        return false // The merchant dismissed the sheet. Let them retry.
    } catch TapToPayError.accountLinkingRequiresiCloudSignIn {
        promptForiCloudSignIn()
        return false
    } catch {
        presentLinkError(error)
        return false
    }
}

import UIKit

// There is no deep link to the Tap to Pay on iPhone screen in Settings.
// Open your app's settings and direct the merchant from there:
if let settingsURL = URL(string: UIApplication.openSettingsURLString) {
    await UIApplication.shared.open(settingsURL)
}
// Then direct the merchant to: Settings > Wallet & Apple Pay > Tap to Pay on iPhone