# Installation and initialization

**Before you start:** you need the five values from [Credentials and environments](/ios/tap-to-pay/credentials), including an activated Device ID from [Set up a Device](/ios/tap-to-pay/device-setup).

## 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](/ios/tap-to-pay/privacy) 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](/ios/tap-to-pay/device-setup). |
| `transactionOptions` | `TransactionOptions` | `TransactionOptions()` | Behavior tuning. See [Transaction options](#transaction-options). |
| `crashReportingEnabled` | `Bool` | `true` | Whether the SDK's diagnostics include crash reporting. See [Privacy and data collection](/ios/tap-to-pay/privacy). |


`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](/ios/tap-to-pay/transactions#prepare-the-reader). |
| `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](/ios/tap-to-pay/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](/ios/tap-to-pay/apple-entitlement) |
| `isAccountLinked() async -> Bool` | [Account linking](/ios/tap-to-pay/account-linking) |
| `linkAccount() async throws` | [Account linking](/ios/tap-to-pay/account-linking) |
| `forceRefreshLinkStatus() async -> Bool` | [Account linking](/ios/tap-to-pay/account-linking) |
| `clearLinkStatus()` | [Account linking](/ios/tap-to-pay/account-linking) |
| `prepareReader() async throws` | [Prepare the reader](/ios/tap-to-pay/transactions#prepare-the-reader) |
| `transactionEvents: AnyPublisher<TapToPayTransactionEvent, Never>` | [Take a payment](/ios/tap-to-pay/transactions#take-a-payment) |
| `startTransaction(amount:currency:type:identityId:) async throws -> TapToPayTransactionResult` | [Take a payment](/ios/tap-to-pay/transactions#take-a-payment) |
| `cancelTransaction() async throws` | [Take a payment](/ios/tap-to-pay/transactions#take-a-payment) |
| `setUserInterfaceLanguage(_:)` | [Localize the payment experience](/ios/tap-to-pay/transactions#localize-the-payment-experience) |
| `refreshConfiguration()` | This page |
| `clearAllCaches()` | This page |


**Next:** [Account linking](/ios/tap-to-pay/account-linking).