Installation and initialization
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Before you start: you need the five values from Credentials and environments, including an activated Device ID from Set up a Device.

Add the package

The SDK is distributed as a binary XCFramework via Swift Package Manager.

In Xcode: File ▸ Add Package Dependencies…, enter the package URL https://github.com/finix-payments/finix-taptopay-ios-sdk, and select Up to Next Major Version starting at 1.0.0. Or add it to your Package.swift as shown.

Bundled dependency

The package includes Datadog dd-sdk-ios 3.6.1 (DatadogCore, DatadogLogs, DatadogCrashReporting), which the SDK uses to report diagnostics and crashes to Finix. Privacy and data collection describes exactly what is collected and how to opt out of crash reporting.

Create a configuration

Build a TapToPayConfiguration and create the SDK entry point, FinixTapToPay.

Initializing the SDK makes no network calls. Authentication happens the first time you link an account, prepare the reader, or start a transaction.

Configuration reference

Field	Type	Default	Description
`credentials`	`APICredentials`	None (required).	Finix API `username` and `password` for the target environment.
`merchant`	`MerchantInfo`	None (required).	The merchant receiving the payments (see below).
`environment`	`Environment`	None (required).	`.sandbox` or `.production`; must match the credentials, merchant, and Device.
`deviceId`	`String`	None (required).	The activated Device ID from Set up a Device.
`transactionOptions`	`TransactionOptions`	`TransactionOptions()`	Behavior tuning. See Transaction options.
`crashReportingEnabled`	`Bool`	`true`	Whether the SDK's diagnostics include crash reporting. See Privacy and data collection.

MerchantInfo fields:

Field	Type	Description
`merchantId`	`String`	The Finix Merchant ID (`MUxxxxxxxxxxxxx`).
`merchantMid`	`String`	The merchant's processing MID. Required; never pass an empty string.
`merchantName`	`String`	Display name; Apple shows it to the Buyer on the tap screen.

Transaction options

Option	Default	Description
`returnReadResultImmediately`	`true`	Dismiss Apple's tap sheet as soon as the card read completes, instead of holding it while the payment processes. Apple recommends this for a smoother checkout flow. Show your own processing screen while the payment completes.
`autoPrepareOnForeground`	`true`	Re-warm the reader automatically when your app returns to the foreground, if a reader session already exists. This does not replace your initial prepare.
`linkStatusCacheDuration`	`300` (seconds)	How long `isAccountLinked()` can return a cached value before re-checking with Apple. Use `forceRefreshLinkStatus()` to bypass the cache.

Crash reporting opt-out. When the SDK initializes its own diagnostics, it also enables crash reporting so Finix can diagnose SDK crashes. If your app ships its own crash reporter, pass crashReportingEnabled: false, because two crash reporters in the same process can conflict. If your app already initializes Datadog before creating the SDK, the flag has no effect: the SDK uses your existing Datadog instance and does not enable crash reporting.

Managing configuration at runtime

Create one FinixTapToPay instance per merchant session and reuse it. Recreate it only when the merchant, MID, or environment changes.
When rebuilding a configuration, don't overwrite a known-good value with an empty one. In particular, don't replace a real merchantMid with "" while a lookup is still in flight. Transactions submitted without a MID fail at processing.
Call refreshConfiguration() if your backend reconfigures the merchant or Device (for example, a terminal-profile change). This invalidates the SDK's cached tokens and reader session, so you must call prepareReader() again before the next transaction.
clearAllCaches() resets all cached state (tokens, link status, session) for a full re-setup. It does not unlink the merchant's Apple Account. See Account linking.

API quick reference

Every member of FinixTapToPay and where this guide covers it:

Member	Covered in
`init(configuration:)`	This page
`static isSupported() -> Bool`	Apple entitlement setup
`isAccountLinked() async -> Bool`	Account linking
`linkAccount() async throws`	Account linking
`forceRefreshLinkStatus() async -> Bool`	Account linking
`clearLinkStatus()`	Account linking
`prepareReader() async throws`	Prepare the reader
`transactionEvents: AnyPublisher<TapToPayTransactionEvent, Never>`	Take a payment
`startTransaction(amount:currency:type:identityId:) async throws -> TapToPayTransactionResult`	Take a payment
`cancelTransaction() async throws`	Take a payment
`setUserInterfaceLanguage(_:)`	Localize the payment experience
`refreshConfiguration()`	This page
`clearAllCaches()`	This page

Next: Account linking.

// Swift Package Manager - add via Xcode:
// File > Add Package Dependencies
// https://github.com/finix-payments/finix-taptopay-ios-sdk
//
// Or in Package.swift:
// dependencies: [
//     .package(url: "https://github.com/finix-payments/finix-taptopay-ios-sdk", from: "1.0.0")
// ],
// targets: [
//     .target(
//         name: "YourApp",
//         dependencies: [
//             .product(name: "FinixTapToPaySDK", package: "finix-taptopay-ios-sdk")
//         ]
//     )
// ]
import FinixTapToPaySDK

import FinixTapToPaySDK

let configuration = TapToPayConfiguration(
    credentials: TapToPayConfiguration.APICredentials(
        username: "USxxxxxxxxxxxxx",
        password: "{your_api_secret}"
    ),
    merchant: TapToPayConfiguration.MerchantInfo(
        merchantId: "MUxxxxxxxxxxxxx",
        merchantMid: "123456789012345",
        merchantName: "Bluebird Coffee"
    ),
    environment: .sandbox,
    deviceId: "DVxxxxxxxxxxxxx"
)

let tapToPay = FinixTapToPay(configuration: configuration)

let configuration = TapToPayConfiguration(
    credentials: credentials,
    merchant: merchant,
    environment: .sandbox,
    deviceId: deviceId,
    transactionOptions: TapToPayConfiguration.TransactionOptions(
        returnReadResultImmediately: true,
        autoPrepareOnForeground: true,
        linkStatusCacheDuration: 300
    ),
    crashReportingEnabled: false // e.g. your app ships its own crash reporter
)

// After your backend reconfigures the merchant or Device:
tapToPay.refreshConfiguration()
// The reader session is now invalid. Prepare again before transacting:
try await tapToPay.prepareReader()

// Full reset of cached SDK state (tokens, link status, session).
// Does NOT unlink the merchant's Apple Account.
tapToPay.clearAllCaches()

// All members of FinixTapToPay:
protocol FinixTapToPayAPI {
    init(configuration: TapToPayConfiguration)
    static func isSupported() -> Bool
    func isAccountLinked() async -> Bool
    func linkAccount() async throws
    func forceRefreshLinkStatus() async -> Bool
    func clearLinkStatus()
    func prepareReader() async throws
    var transactionEvents: AnyPublisher<TapToPayTransactionEvent, Never> { get }
    func startTransaction(
        amount: Int,
        currency: String,
        type: TransactionType,
        identityId: String?
    ) async throws -> TapToPayTransactionResult
    func cancelTransaction() async throws
    func setUserInterfaceLanguage(_ language: Locale.Language?)
    func refreshConfiguration()
    func clearAllCaches()
}