> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/merchant-tokenization/sdk-integration/integration/ios.md).

# iOS

Use this guide to integrate the **Thales SDK** into an iOS merchant native application.

## Delivery package <a href="#delivery-packages" id="delivery-packages"></a>

The SDK delivery package includes:

<table><thead><tr><th width="100">Name</th><th>Description</th></tr></thead><tbody><tr><td>Binaries</td><td>Release and debug variants of the Thales SDK.</td></tr><tr><td>Demo</td><td>Sample project that shows how to integrate and use the Thales SDK.</td></tr><tr><td>Apidoc</td><td>Thales SDK API documentation.</td></tr><tr><td>License</td><td>Licenses for third-party frameworks shipped with the Thales SDK.</td></tr></tbody></table>

## Integrate the SDK <a href="#application-integration" id="application-integration"></a>

1. Create a folder called `Framework`.
2. Copy the `.xcframework` bundles from `Binaries/<Release|Debug>/` into the `Framework` folder.

<figure><img src="/files/NFOc5X0eUW6p6g1kZ45R" alt=""><figcaption><p>Example <code>Framework</code> folder containing the SDK <code>.xcframework</code> bundles.</p></figcaption></figure>

3. Drag `TMGSDK.xcframework` and `SecureLogAPI.xcframework` from the `Framework` folder to **Frameworks, Libraries, and Embedded Content** in your target settings.

<figure><img src="/files/IIq9FABNQrLu1aJfFDid" alt=""><figcaption><p>Embed the SDK frameworks in your app target.</p></figcaption></figure>

4. Add the Face ID usage description to your app’s `Info.plist`.

<figure><img src="/files/OGKpFDltyKUqBGRvGLa3" alt=""><figcaption><p>Add the Face ID usage description in <code>Info.plist</code>.</p></figcaption></figure>

## Configure the SDK <a href="#sdk-configuration" id="sdk-configuration"></a>

Configure Thales SDK before calling any SDK API.

Build a `TMGClientConfiguration` with the required parameters:

* Server URL
* Server certificate
* Key identifier
* certificate PINs

#### 1. Create a `TMGClientConfiguration`

Get the server URL, server certificate, and key identifier during onboarding.

```swift
let serverURL = ""
let serverCertificate = ""
let serverKeyID = ""
let configuration = TMGClientConfiguration(serverURL: serverURL,
                                           serverCertificate: Data(serverCertificate.utf8),
                                           serverKeyID: serverKeyID)
```

#### 2. Create a `VisaCTFHelper`

Create the helper to start device binding and authenticate transactions for Visa CTF and DAF.

```swift
do {
      let visaCTFHelper = try TMGClient.sharedInstance.createVisaCTFHelper(withConfiguration: configuration)
} catch let error {
  // Handle the error
}
```

#### 3. Create a `MastercardTAFHelper`

Create the helper to start device binding and authenticate transactions for Mastercard TAF.

```swift
do {
      let mastercardTAFHelper = try TMGClient.sharedInstance.createMastercardTAFHelper(withConfiguration: configuration)
  } catch let error {
      // Handle the error
  }
```

If the SDK cannot create the helper, it throws an error.

{% hint style="info" %}
Use each SDK variant only for its intended environment. When you create a `VisaCTFHelper`, the SDK returns `deviceEnvironmentUnsafe` in these cases:

* `Debug`: You sign the app with a distribution or ad-hoc certificate.
* `Release`: You debug the app, or you launch it from Xcode or `xcodebuild`. If you hit this error, stop debugging and relaunch the app on the device.
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/merchant-tokenization/sdk-integration/integration/ios.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.