Frames iOS SDK

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 under the MIT license. For the SDK's API information, refer to the Frames iOS SDK API reference.

We stay up-to-date with the latest Payment Card Industry Data Security Standards (PCI DSS). Read our PCI compliance 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 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.

Integrate our Frames iOS SDK into your application's source code.
Display the payment forms we provide to collect your customer's payment information and exchange this for a secure token. This is the tokenization step.
Use the secure token to make a payment request.

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

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.

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.

Note

You must have CocoaPods 1.10 or later installed.

Add the SDK to your app's Podfile:


1source 'https://github.com/CocoaPods/Specs.git'
2platform :ios, '12.0'
3use_frameworks!
4
5pod 'PhoneNumberKit', :git => 'https://github.com/marmelroy/PhoneNumberKit'
6
7target '<Your Target Name>' do
8    pod 'Frames', '~> 4'
9end

Then, run the following command in the terminal:


1$ pod install

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


1// Import the SDK
2import Frames
3
4// Defines customer information to for use in a new BillingForm object
5let country = Country(iso3166Alpha2: "GB")
6
7let address = Address(
8    addressLine1: "123 High St.",
9    addressLine2: "Flat 456",
10    city: "London",
11    zip: "SW1A 1AA",
12    country: country)
13
14let phone = Phone(number: "+44 1234567890",
15    country: country)
16
17// Creates a new BillingForm and populates it with the customer data defined above
18let billingFormData = BillingForm(
19    name: "John Smith",
20    address: address,
21    phone: phone)
22
23/* Configures the payment environment. Providing billingFormData is optional,
24but doing so can simplify your customer's checkout experience and improves the
25chances of successful tokenization */
26
27let configuration = PaymentFormConfiguration(
28    apiKey: "<Your Public Key>",
29    environment: .sandbox,
30    supportedSchemes: [.visa, .maestro, .mastercard],
31    billingFormData: billingFormData)
32
33// Configures tokenization success and failure states
34let completion: ((Result<TokenDetails, TokenRequestError>) -> Void) = { result in
35    switch result {
36    case .failure(let failure):
37        if failure == .userCancelled {
38            /* Depending on needs, User Cancelled can be handled as an individual
39            failure to complete, an error, or simply a callback that control is returned */
40            print("User has cancelled")
41        } else {
42            print("Failed, received error", failure.localizedDescription)
43        }
44    case .success(let tokenDetails):
45        print("Success, received token", tokenDetails.token)
46    }
47}
48
49// Displays the forms to the user to collect payment information
50let framesViewController = PaymentFormFactory.buildViewController(
51    configuration: configuration,
52    style: PaymentStyle(
53        paymentFormStyle: DefaultPaymentFormStyle(),
54        billingFormStyle: DefaultBillingFormStyle()),
55    completionHandler: completion
56)
57navigationController.pushViewController(framesViewController, animated: true)

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, 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

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 redirection 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.


1let threeDSWebViewController = ThreedsWebViewController(
2    successUrl: "https://example.com/success",
3    failUrl: "https://example.com/failure")
4threeDSWebViewController.url = "https://example.com/3ds"
5threeDSWebViewController.delegate = self


1extension ViewController: ThreedsWebViewControllerDelegate {
2
3    func threeDSWebViewControllerAuthenticationDidSucceed(_ threeDSWebViewController: ThreedsWebViewController, token: String?) {
4        // Handle successful 3DS.
5    }
6
7    func threeDSWebViewControllerAuthenticationDidFail(_ threeDSWebViewController: ThreedsWebViewController) {
8        // Handle failed 3DS.
9    }
10
11}

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


1func handle(payment: PKPayment) {
2    // Create a CheckoutAPIClient instance with your public key.
3
4    let checkoutAPIClient = CheckoutAPIClient(
5        publicKey: "<Your Public Key>",
6        environment: .sandbox)
7
8    // Get the data containing the encrypted payment information.
9    let paymentData = payment.token.paymentData
10
11    // Request an Apple Pay token.
12    checkoutAPIClient.createApplePayToken(paymentData: paymentData) { result in
13        switch result {
14        case .success(let response):
15            print(response)
16        case .failure(let error):
17            print(error.localizedDescription)
18        }
19    }
20}

Now that you have the card token, you can request a payment.

Customize the Frames iOS SDK

Customize the forms used to collect payment information in your iOS app.

Frames iOS SDK

Information

PCI DSS compliance

How it works

Integrate with our Frames iOS SDK

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

Note

Step 2: Configure your integration

Step 3: (Optional) Customize your payment forms

Handle 3D Secure

Create and configure a `ThreedsWebViewController`

Handle the result by adding conformance to `ThreedsWebViewControllerDelegate`

Apple Pay example

Related topics

Customize the Frames iOS SDK

Information

PCI DSS compliance

How it works

Integrate with our Frames iOS SDK

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

Step 2: Configure your integration

Step 3: (Optional) Customize your payment forms

Handle 3D Secure

Create and configure a ThreedsWebViewController

Handle the result by adding conformance to ThreedsWebViewControllerDelegate

Apple Pay example

Related topics

Customize the Frames iOS SDK

Create and configure a `ThreedsWebViewController`

Handle the result by adding conformance to `ThreedsWebViewControllerDelegate`