Skip to content

Installation and initialization

Add the package

Distributed as a binary XCFramework via Swift Package Manager.

  • Package URL: https://github.com/finix-payments/finix-taptopay-ios-sdk
  • Version: Use the latest release.
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. See Privacy and data collection for what is collected and how to opt out.

Create a configuration

FinixTapToPay is the SDK entry point. Build a TapToPayConfiguration and pass it to FinixTapToPay(configuration:).

Initialization makes no network calls. Authentication happens on the first linkAccount(), prepareReader(), or startTransaction().

Configuration reference
FieldTypeDefaultDescription
credentialsTapToPayConfiguration.APICredentialsNone (required).Finix API username and password for the target environment.
merchantTapToPayConfiguration.MerchantInfoNone (required).The merchant receiving the payments (see below).
environmentTapToPayConfiguration.EnvironmentNone (required)..sandbox or .production; must match the credentials, merchant, and Device.
deviceIdStringNone (required).The activated Device ID from Set up a Device.
transactionOptionsTapToPayConfiguration.TransactionOptionsTransactionOptions()Behavior tuning. See Transaction options below.
crashReportingEnabledBooltrueWhether the SDK's diagnostics include crash reporting. See Privacy and data collection.
MerchantInfo fields
FieldTypeDescription
merchantIdStringThe Finix Merchant ID (MUxxxxxxxxxxxxx). The SDK resolves the merchant's processing MID internally from this value.
merchantNameStringDisplay name; Apple shows it to the Buyer on the tap screen.

Transaction options

OptionDefaultDescription
returnReadResultImmediatelytrueDismiss 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.
autoPrepareOnForegroundtrueRe-warm the reader automatically when your app returns to the foreground, if a reader session already exists. This does not replace your initial prepare.
linkStatusCacheDuration300 (seconds)How long isAccountLinked() can return a cached value before re-checking with Apple. Use forceRefreshLinkStatus() to bypass the cache.

Crash reporting: crashReportingEnabled is true by default. Set to false if your app ships its own crash reporter; two reporters in the same process can conflict. If your app already initializes Datadog before creating FinixTapToPay, the flag has no effect: the SDK uses the existing Datadog instance and does not enable crash reporting.

Managing configuration at runtime

MethodBehavior
refreshConfiguration()Invalidates cached tokens and reader session. Call after a backend-side merchant or Device reconfiguration. Requires prepareReader() before the next transaction.
clearAllCaches()Resets all cached state (tokens, link status, session). Does not unlink the merchant's Apple Account; see Account linking.

Instance lifecycle: reuse one FinixTapToPay instance per merchant session. Recreate only when the merchant or environment changes.

FinixTapToPay members

// 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",
        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()
}