Skip to content

Account linking

linkAccount() presents Apple's Terms and Conditions sheet and links the merchant's Apple Account to Tap to Pay on iPhone. Payments cannot be accepted until the link is established.

Behavior

  • The link is maintained at the iOS system level. It survives app launches and can survive app reinstalls.
  • Linking requires an iCloud sign-in on the device. Without one, linkAccount() throws .accountLinkingRequiresiCloudSignIn.
  • Linking requires a device passcode (Settings → Face ID & Passcode). Without one, linking fails.
  • The Terms must be accepted by a user authorized to bind the merchant (owner or administrator). Apple's App Review requires that your app gate the Terms sheet behind this check.

Check link status

MethodBehavior
isAccountLinked() async -> BoolReturns Apple's acceptance status. Cached for up to linkStatusCacheDuration (default 300s). A true result is reliable; a false result may also indicate a failed check or an unprovisioned device.
forceRefreshLinkStatus() async -> BoolBypasses the cache and re-queries Apple.
clearLinkStatus()Drops the cached status so the next isAccountLinked() re-queries Apple.

Apple's answer is the source of truth. Do not persist link status in your own flag or database; App Review checks for this.

Link the account

linkAccount() async throws presents Apple's Terms and Conditions sheet. On acceptance, the Apple Account is linked to Tap to Pay on iPhone for the current merchant.

ErrorMeaning
.accountAlreadyLinkedThe merchant has already accepted the Terms. Treat as success.
.accountLinkingRequiresiCloudSignInThe device is not signed in to iCloud.

Manage or unlink the account

There is no SDK or API to unlink an Apple Account; the link lives at the iOS system level. clearLinkStatus() and clearAllCaches() only reset local caches and do not unlink.

Deleting and reinstalling the app usually (but not always) returns to an unlinked state (see Behavior). To guarantee an 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 Settings → Wallet & Apple Pay → Tap to Pay on iPhone. iOS does not expose a deep link to that screen.

// 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