Frames iOS
Requirements
- iOS 10.0+
- Xcode 12.4+
- Swift 5.3+
Documentation
Further information on using the Frames SDK is available in the integration guide.
Frames for iOS provides a convenient solution that can take the customer's sensitive information and exchange them for a secure token that can be used within Checkout.com's infrastructure.
Frames can be integrated in 2 ways:
-
Integrated with the UI Embed the fully customisable UI provided by the SDK to accept card details, customer name and billling details and exchange them for a secure token. (See the
CardViewControllertab) -
Integrated without the UI Use the provided API to send sensitive data to the Checkout.com server and retrieve the secure token (See the
Headlesstab).
You can find the Frames API reference on this website.
- Usage
- Customizing the card view
- Walkthrough
Installation
CocoaPods
CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:
$ gem install cocoapods
CocoaPods 1.10.0+ is required to build Frames.
To integrate Frames into your Xcode project using CocoaPods, specify it in your Podfile:
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:
$ pod install
Carthage
Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.
You can install Carthage with Homebrew using the following command:
$ brew update
$ brew install carthage
To integrate Frames into your Xcode project using Carthage, specify it in your Cartfile:
github "checkout/frames-ios" ~> 3
Run carthage update --use-xcframeworks to build the framework and drag the built Frames into your Xcode project.
Swift Package Manager
Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.
Once you have your Swift package set up, adding Frames as a dependency is as easy as adding it to the dependencies value of your Package.swift.
dependencies: [
.package(url: "https://github.com/checkout/frames-ios.git", .upToNextMajor(from: "3.0.0"))
]
Usage
Import the SDK:
import Frames
Using the CardViewController UI
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: false)
}
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.
}
}
Headless Mode
// 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)
}
}
Using Methods available in FramesIos
You can find more examples on the usage guide.
Create the API Client CheckoutAPIClient:
// 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)
Create the CardUtils instance:
let cardUtils = CardUtils()
Use CardUtils to verify card number:
// Verify card number.
let cardNumber = "4242424242424242"
let isValidCardNumber = cardUtils.isValid(cardNumber: cardNumber)
print(isValidCardNumber) // true
Validate a CVV with CardUtils
// 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
// 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
let cardNumber = "4242424242424242"
guard let cardType = cardUtils.getTypeOf(cardNumber: cardNumber) else { return }
print(cardType.name) // Visa
Format a card number with CardUtils
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
let cardNumber = "4242 | 4242 | 4242 | 4242 "
let standardizedCardNumber = cardUtils.standardize(cardNumber: cardNumber)
print(standardizedCardNumber) // "4242424242424242"
Create the card token request CkoCardTokenRequest:
// 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.
Prompt for CVV confirmation
Create and configure a CvvConfirmationViewController.
let cvvConfirmationViewController = CvvConfirmationViewController()
cvvConfirmationViewController.delegate = self
Handle the result by adding conformance to CvvConfirmationViewControllerDelegate.
extension ViewController: CvvConfirmationViewControllerDelegate {
func onConfirm(controller: CvvConfirmationViewController, cvv: String) {
// Handle cvv.
}
func onCancel(controller: CvvConfirmationViewController) {
// Handle cancellation.
}
}
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 Checkout.com 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.
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.
extension ViewController: ThreedsWebViewControllerDelegate {
func threeDSWebViewControllerAuthenticationDidSucceed(_ threeDSWebViewController: ThreedsWebViewController, token: String?) {
// Handle successful 3DS.
}
func threeDSWebViewControllerAuthenticationDidFail(_ threeDSWebViewController: ThreedsWebViewController) {
// Handle failed 3DS.
}
}
Customize with CheckoutTheme
Further documentation about customizing Frames is available from the customization guide.
CheckoutTheme.primaryBackgroundColor = .purple
CheckoutTheme.secondaryBackgroundColor = .magenta
CheckoutTheme.tertiaryBackgroundColor = .red
CheckoutTheme.color = .white
CheckoutTheme.secondaryColor = .lightGray
CheckoutTheme.errorColor = .blue
CheckoutTheme.chevronColor = .white
CheckoutTheme.font = UIFont(name: "Chalkboard SE", size: 12)!
License
Frames iOS is released under the MIT license. See LICENSE for details.
Currently the ViewController holds a reference to the viewModel under 2 separate properties:
MVVM (Model - View - ViewModel) is a very straight forward pattern and to fix our current implementation we would be looking to drop the "delegate" from the current implementation.
The previous Solution is a natural step into fixing the shortcomings of current Problem, it also reduces fragility when considering any future work, but the flow can further be improved with a minor tweak.
766 Dec 28, 2022
1 Oct 1, 2021
3 Apr 18, 2022
1.6k Jan 6, 2023
1 Jan 7, 2023
253 Dec 18, 2022
520 Jan 4, 2023
6.1k Jan 7, 2023
104 Dec 15, 2022
170 Dec 26, 2022
973 Dec 18, 2022
2 Sep 26, 2022
40 Nov 24, 2022
334 Nov 28, 2022
362 Nov 29, 2022
135 Sep 9, 2022
0 Dec 28, 2021
0 Dec 20, 2021
9 Jun 24, 2022