# Frames iOS SDK

> **Note**
>
> Frames will be deprecated on June 30, 2026. [Upgrade to Flow for mobile](https://www.checkout.com/docs/payments/accept-payments/upgrade-to-flow-from-frames/upgrade-from-frames-for-ios.md), our pre-built, customizable payment user interface. Flow provides a more flexible, scalable, and feature-rich integration, as well as access to additional payment methods.

Our Frames iOS SDK allows you to accept online payments from all major credit cards and offers multiple levels of customization to suit your requirements.

> **Information**
>
> Our Frames iOS SDK is available on [GitHub](https://github.com/checkout/frames-ios) under the MIT license. For the SDK's API information, refer to the [Frames iOS SDK API reference](https://checkout.github.io/frames-ios/index.html).

---

## PCI DSS compliance

We stay up-to-date with the latest Payment Card Industry Data Security Standards (PCI DSS). Read our [PCI compliance](https://www.checkout.com/docs/payments/regulation-support/pci-compliance.md) documentation to learn how we can help you to be compliant.

Based on these standards, we advise you to use one of our [UI-based solutions](https://www.checkout.com/docs/developer-resources/sdks/frames-sdks/frames-ios-sdk/customize-the-frames-ios-sdk.md) of the Frames SDKs to remain at the lowest level of compliance (SAQ-A).

If you build your own UI, or use the Frames SDKs in another way, you may end up needing to adhere to a higher level of compliance.

---

## How it works

1. [Integrate our Frames iOS SDK](#Step_1:_Add_the_SDK_to_your_application's_source_code) into your application's source code.
2. [Display the payment forms](#Step_2:_Configure_your_integration) we provide to collect your customer's payment information and exchange this for a secure token. This is the tokenization step.
3. Use the secure token to [make a payment request](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payments-api.md#Request_a_payment_with_a_token).

---

## Integrate with our Frames iOS SDK

Before you follow this guide to integrate our Frames iOS SDK, make sure you have the following installed on your desktop:

- Swift 5.3 or later
- Xcode 12.4 or later, with iOS version 12 or later running in the simulator

### Step 1: Add the SDK to your application's source code

We recommend using Swift Package Manager to add our SDK due to its ease of use, but we also support integration via the CocoaPods dependency manager.

**Swift Package Manager**

Add our GitHub repository's URL (`https://github.com/checkout/frames-ios`) as a package dependency in your app.

For detailed steps, follow the [guide on Apple's documentation](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).

**CocoaPods**

> **Note**
>
> You must have CocoaPods 1.10 or later installed.

Add the SDK to your app's `Podfile`:

```rb
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!

pod 'PhoneNumberKit', :git => 'https://github.com/marmelroy/PhoneNumberKit'

target '<Your Target Name>' do
    pod 'Frames', '~> 4'
end
```

Then, run the following command in the terminal:

```bash
$ pod install
```

### Step 2: Configure your integration

In a script in your project, add the following code:

```swift
// Import the SDK
import Frames

// Defines customer information to for use in a new BillingForm object
let country = Country(iso3166Alpha2: "GB")

let address = Address(
    addressLine1: "123 High St.",
    addressLine2: "Flat 456",
    city: "London",
    zip: "SW1A 1AA",
    country: country)

let phone = Phone(number: "+44 1234567890",
    country: country)

// Creates a new BillingForm and populates it with the customer data defined above
let billingFormData = BillingForm(
    name: "John Smith",
    address: address,
    phone: phone)

/* Configures the payment environment. Providing billingFormData is optional,
but doing so can simplify your customer's checkout experience and improves the
chances of successful tokenization */

let configuration = PaymentFormConfiguration(
    apiKey: "<Your public key>",
    environment: .sandbox,
    supportedSchemes: [.visa, .maestro, .mastercard],
    billingFormData: billingFormData)

// Configures tokenization success and failure states
let completion: ((Result<TokenDetails, TokenRequestError>) -> Void) = { result in
    switch result {
    case .failure(let failure):
        if failure == .userCancelled {
            /* Depending on needs, User Cancelled can be handled as an individual
            failure to complete, an error, or simply a callback that control is returned */
            print("User has canceled")
        } else {
            print("Failed, received error", failure.localizedDescription)
        }
    case .success(let tokenDetails):
        print("Success, received token", tokenDetails.token)
    }
}

// Displays the forms to the user to collect payment information
let framesViewController = PaymentFormFactory.buildViewController(
    configuration: configuration,
    style: PaymentStyle(
        paymentFormStyle: DefaultPaymentFormStyle(),
        billingFormStyle: DefaultBillingFormStyle()),
    completionHandler: completion
)
navigationController.pushViewController(framesViewController, animated: true)
```

### Step 3: (Optional) Customize your payment forms

If you want to change the styling of the forms displayed to the customer, you can do so using the `paymentFormStyle` and `billingFormStyle` objects from the example in the previous step.

You can choose between three different options for [customization](https://www.checkout.com/docs/developer-resources/sdks/frames-sdks/frames-ios-sdk/customize-the-frames-ios-sdk.md), depending on how much control you need over the forms' UI design. In order of increasing complexity, these are:

- default form styling, which allows you to modify the fonts and font colors used in the default forms
- themed form styling, which allows you to apply a custom theme to the preset components
- custom form styling, which allows you to build and define your own components

---

## Handle 3D Secure

When you send a 3D secure charge request from your server, you will get back a 3D Secure URL. This is available from `_links.redirect.href` within the JSON response. You can then pass the 3D Secure URL to a `ThreedsWebViewController` in order to handle the verification.

The redirect URLs (`success_url` and `failure_url`) are set in the Dashboard, but they can be overwritten in the charge request sent from your server. It is important to provide the correct URLs to ensure a successful payment flow.

### Create and configure a `ThreedsWebViewController`

```swift
let threeDSWebViewController = ThreedsWebViewController(
    successUrl: "https://example.com/success",
    failUrl: "https://example.com/failure")
threeDSWebViewController.url = "https://example.com/3ds"
threeDSWebViewController.delegate = self
```

### Handle the result by adding conformance to `ThreedsWebViewControllerDelegate`

```swift
extension ViewController: ThreedsWebViewControllerDelegate {

    func threeDSWebViewControllerAuthenticationDidSucceed(_ threeDSWebViewController: ThreedsWebViewController, token: String?) {
        // Handle successful 3DS.
    }

    func threeDSWebViewControllerAuthenticationDidFail(_ threeDSWebViewController: ThreedsWebViewController) {
        // Handle failed 3DS.
    }

}
```

---

## Apple Pay example

Our Frames iOS SDK also supports handling `PKPayment` token data from Apple Pay.

```swift
func handle(payment: PKPayment) {
    // Create a CheckoutAPIClient instance with your public key.

    let checkoutAPIClient = CheckoutAPIClient(
        publicKey: "<Your public key>",
        environment: .sandbox)

    // Get the data containing the encrypted payment information.
    let paymentData = payment.token.paymentData

    // Request an Apple Pay token.
    checkoutAPIClient.createApplePayToken(paymentData: paymentData) { result in
        switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error.localizedDescription)
        }
    }
}
```

[Read more about offering Apple Pay in your app](https://developer.apple.com/documentation/passkit/apple_pay/offering_apple_pay_in_your_app).

Now that you have the card token, you can [request a payment](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payments-api.md#Request_a_payment_with_a_token).

---

## Related topics

- [Customize the Frames iOS SDK](https://www.checkout.com/docs/developer-resources/sdks/frames-sdks/frames-ios-sdk/customize-the-frames-ios-sdk.md): Customize the forms used to collect payment information in your iOS app.