Skip to content

iOS SDK

Last updated: 25th May 2022

Start accepting online payments in just a few minutes with our iOS SDK. It's quick and easy to integrate, accepts online payments from all major credit cards, and is customizable to your brand.

Minimum requirements

To use the iOS SDK, make sure you are working with:

  • iOS 10.0+
  • Xcode 12.4+
  • Swift 5.3+

Our iOS SDK is released under the MIT license.

How it works

  1. Choose whether to use the pre-built UI, or build your own payment form and use our iOS SDK in a headless mode.
  2. Our iOS SDK is then used to take your customer's sensitive information and exchange them for a secure token. This process is called tokenization. Once you have the card token, you're ready to make the payment request.
ios

Demo (our pre-built UI)

demo ios

Integrate with our iOS SDK

Before you start

Make sure you have your public_key. You can find it in the Hub, under Settings > Channels. If you don't have an account with us yet, you can request a free test one.

Step 1: Install project dependencies

We've provided examples for the dependency managers CocoaPods, Carthage and Swift Package Manager.

    If you are using CocoaPods, make sure you have version 1.1+.

    To integrate this SDK into your Xcode project using CocoaPods, specify it in your Podfile:

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

    Then run the following command in your terminal:

    1
    $ pod install

    We regularly release new versions of the iOS SDK with additional features and bug fixes, so please routinely update and test your app with the latest framework version.

    Step 2: Import the iOS SDK and choose your approach

    Import the SDK into your class.

    1
    import Frames

    Decide whether you would like to use the CardViewController provided as part of this SDK, which allows users to enter their card details, or whether you prefer full control in the headless version.

      You can modify the card view after initialization.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      class ViewController: UIViewController, CardViewControllerDelegate {
      // Create a CheckoutAPIClient instance with your public key.
      let checkoutAPIClient = CheckoutAPIClient(
      publicKey: "<Your Public Key>",
      environment: .sandbox)
      override func viewDidLoad() {
      super.viewDidLoad()
      // Create the CardViewController.
      let cardViewController = CardViewController(
      checkoutApiClient: checkoutAPIClient,
      cardHolderNameState: .hidden,
      billingDetailsState: .hidden)
      // Set the CardViewController delegate.
      cardViewController.delegate = self
      // Replace the bar button with Pay.
      cardViewController.rightBarButtonItem = UIBarButtonItem(
      title: "Pay",
      style: .done,
      target: nil,
      action: nil)
      // (Optional) Specify which schemes are allowed.
      cardViewController.availableSchemes = [.visa, .mastercard]
      // Push the cardViewController onto the navigation stack.
      navigationController?.pushViewController(cardViewController, animated: true)
      }
      func onTapDone(controller: CardViewController, cardToken: CkoCardTokenResponse?, status: CheckoutTokenStatus) {
      // Called when the tokenization request has completed.
      print(cardToken ?? "cardToken is nil")
      }
      func onSubmit(controller: CardViewController) {
      // Called just before a create card token request is made.
      }
      }

      Available methods

      Two classes are available globally: CheckoutAPIClient and CardUtils. CheckoutAPIClient is used to call the Checkout API with your public key. CardUtils contains methods to use for handling a payment form.

      Create an API Client instance

      You can see the API Client instance in both the headless and pre-built UI examples above.

      1
      2
      3
      4
      // Replace "pk_test_6ff46046-30af-41d9-bf58-929022d2cd14" with your own public key.
      let checkoutAPIClient = CheckoutAPIClient(
      publicKey: "pk_test_6ff46046-30af-41d9-bf58-929022d2cd14",
      environment: .sandbox)

      CardUtils

      When building your own custom UI using the headless mode, you can use the CardUtils class to verify card information.

      Create a CardUtils instance

      1
      let cardUtils = CardUtils()

      Verify a card number with CardUtils

      1
      2
      3
      4
      5
      6
      // Verify card number.
      let cardNumber = "4242424242424242"
      let isValidCardNumber = cardUtils.isValid(cardNumber: cardNumber)
      print(isValidCardNumber) // true

      Validate a CVV with CardUtils

      1
      2
      3
      4
      5
      6
      7
      8
      // Verify CVV.
      let cardNumber = "4242424242424242"
      guard let cardType = cardUtils.getTypeOf(cardNumber: cardNumber) else { return }
      let cvv = "100"
      let isValidCVV = cardUtils.isValid(cvv: cvv, cardType: cardType)
      print(isValidCVV) // true

      Validate an expiration date with CardUtils

      1
      2
      3
      4
      5
      6
      7
      8
      9
      // Verify expiration date.
      let expirationMonth = "01"
      let expirationYear = "29"
      let isValidExpiration = cardUtils.isValid(
      expirationMonth: expirationMonth,
      expirationYear: expirationYear)
      print(isValidExpiration) // true

      Get information about a card number with CardUtils

      1
      2
      3
      let cardNumber = "4242424242424242"
      guard let cardType = cardUtils.getTypeOf(cardNumber: cardNumber) else { return }
      print(cardType.name) // Visa

      Format a card number with CardUtils

      1
      2
      3
      4
      5
      6
      let cardNumber = "4242424242424242"
      guard let cardType = cardUtils.getTypeOf(cardNumber: cardNumber) else { return }
      let formattedCardNumber = cardUtils.format(cardNumber: cardNumber, cardType: cardType)
      print(formattedCardNumber) // 4242 4242 4242 4242

      Standardize a card number with CardUtils

      1
      2
      3
      4
      let cardNumber = "4242 | 4242 | 4242 | 4242 "
      let standardizedCardNumber = cardUtils.standardize(cardNumber: cardNumber)
      print(standardizedCardNumber) // "4242424242424242"

      Create a prompt for CVV confirmation

      Create and configure a CvvConfirmationViewController

      1
      2
      let cvvConfirmationViewController = CvvConfirmationViewController()
      cvvConfirmationViewController.delegate = self

      Handle the result by adding conformance to CvvConfirmationViewControllerDelegate

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      CvvConfirmationViewControllerDelegate.
      extension ViewController: CvvConfirmationViewControllerDelegate {
      func onConfirm(controller: CvvConfirmationViewController, cvv: String) {
      // Handle cvv.
      }
      func onCancel(controller: CvvConfirmationViewController) {
      // Handle cancellation.
      }
      }

      Create a card token

      Here we use the method createCardToken.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      // Create a CheckoutAPIClient instance with your public key.
      let checkoutAPIClient = CheckoutAPIClient(
      publicKey: "<Your Public Key>",
      environment: .sandbox)
      let phoneNumber = CkoPhoneNumber(
      countryCode: "44",
      number: "7700900000")
      let address = CkoAddress(
      addressLine1: "Wenlock Works",
      addressLine2: "Shepherdess Walk",
      city: "London",
      state: "London",
      zip: "N1 7BQ",
      country: "GB")
      // Create a CardTokenRequest instance with the phoneNumber and address values.
      let cardTokenRequest = CkoCardTokenRequest(
      number: "4242424242424242",
      expiryMonth: "01",
      expiryYear: "29",
      cvv: "100",
      name: "Test Customer",
      billingAddress: address,
      phone: phoneNumber)
      // Request the card token.
      checkoutAPIClient.createCardToken(card: cardTokenRequest) { result in
      switch result {
      case .success(let response):
      print(response)
      case .failure(let error):
      print(error.localizedDescription)
      }
      }

      The completion handler here provides a Result<CkoCardTokenResponse, NetworkError> value.


      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
      2
      3
      4
      5
      let threeDSWebViewController = ThreedsWebViewController(
      successUrl: "http://example.com/success",
      failUrl: "http://example.com/failure")
      threeDSWebViewController.url = "http://example.com/3ds"
      threeDSWebViewController.delegate = self

      Handle the result by adding conformance to ThreedsWebViewControllerDelegate

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

      Apple Pay example

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

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      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.

      Learn more about the iOS SDK

      Customization

      Although we kept our demo simple, you have a lot of control over the appearance of your form – from the colors and styling, to whether you want to display one input field or several. Check out our customization guide for more details and examples.


      Next steps

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