Skip to content

iOS SDK

Last updated: November 30, 2022

Our 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 iOS SDK is provided under the MIT license.


PCI DSS compliance

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 SDKs in another way, you may end up needing to adhere to a higher level of compliance.


How it works

  1. Integrate our iOS SDK into your application's source code.
  2. 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.
  3. Use the secure token to make a payment request.
ios

Integrate with our iOS SDK

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

  • Swift 5.3 or above
  • Xcode 12.4 or above, with iOS version 12 or above 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 and Carthage dependency managers.

    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.

    Step 2: Configure your integration

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

    1
    // Import the SDK
    2
    import Frames
    3
    4
    // Defines customer information to for use in a new BillingForm object
    5
    let country = Country(iso3166Alpha2: "GB")
    6
    7
    let address = Address(
    8
    addressLine1: "221B Baker Street",
    9
    addressLine2: "Marylebone",
    10
    city: "London",
    11
    state: "London",
    12
    zip: "NW1 6XE",
    13
    country: country)
    14
    15
    let phone = Phone(number: "+44 2072243688",
    16
    country: country)
    17
    18
    // Creates a new BillingForm and populates it with the customer data defined above
    19
    let billingFormData = BillingForm(
    20
    name: "John Smith",
    21
    address: address,
    22
    phone: phone)
    23
    24
    /* Configures the payment environment. Providing billingFormData is optional,
    25
    but doing so can simplify your customer's checkout experience and improves the
    26
    chances of successful tokenization */
    27
    28
    let configuration = PaymentFormConfiguration(
    29
    apiKey: "<Your Public Key>",
    30
    environment: .sandbox,
    31
    supportedSchemes: [.visa, .maestro, .mastercard],
    32
    billingFormData: billingFormData)
    33
    34
    // Configures tokenization success and failure states
    35
    let completion: ((Result<TokenDetails, TokenRequestError>) -> Void) = { result in
    36
    switch result {
    37
    case .failure(let error):
    38
    print("Failed, received error", error.localizedDescription)
    39
    case .success(let tokenDetails):
    40
    print("Success, received token", tokenDetails.token)
    41
    }
    42
    }
    43
    44
    // Displays the forms to the user to collect payment information
    45
    let framesViewController = PaymentFormFactory.buildViewController(
    46
    configuration: configuration,
    47
    style: PaymentStyle(
    48
    paymentFormStyle: DefaultPaymentFormStyle(),
    49
    billingFormStyle: DefaultBillingFormStyle()),
    50
    completionHandler: completion
    51
    )
    52
    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.

    The default payment form
    The default billing form

    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: use the default forms with custom fonts and font colors.
    • Themed form styling: use our themed option to apply a custom theme to the components displayed, for greater control over the look of your forms.
    • Custom form styling: use our fully custom option to build and define your own components to display across the forms.

    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 redirection URLs (success_url and failure_url) are set in the Hub, 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

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

    Handle the result by adding conformance to ThreedsWebViewControllerDelegate

    1
    extension 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
    }

    Apple Pay example

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

    1
    func 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
    }
    Read more about offering Apple Pay in your app.

    Next steps

    Now that you've got your card token, you're ready to request a card payment.