Follow the simple steps below and get started developing.

1. Add iOS Framework


The Simplify SDK requires a minimum of iOS 13+ and is compatible with Swift 5 projects.


To add the Simplify SDK into your Xcode Project, you can drag the Simplify.xcframework folder into your Xcode project and add the library to your target's "Frameworks, Libraries and Embedded Content".

You can then import Simplify the framework where needed.

// AppDelegate.swift
import Simplify

You can also set the Simplify.xcframework up as a local swift package with the .binaryTarget option.

The SDK depends on the Gateway.xcframework and uSDK.xcframework bundled in the zip file. Make sure this is also included in your project as above.

2. Collect Card Information

Setting API keys

Before it can be used, the iOS SDK must be initialized. It's recommended this operation be performed in your AppDelegate class.

// AppDelegate.swift
    apiKey: "Your Public Key"

Payer Authentication

3-D Secure or 3DS authentication is designed to protect online purchases against credit card fraud by allowing you to authenticate the payer before submitting an Authorization or Pay transaction.

EMV 3DS, also known as 3DS2, is the new version designed to enhance security in online purchases while providing frictionless checkouts to payers who are considered low risk by the Access Control Server (ACS). The ACS may determine the risk using information provided by the merchant, device fingerprinting, and/or previous interactions with the payer. The ACS subjects the payer to a challenge (for example, entering a PIN) only where additional verification is required to authenticate the payer thereby providing increased conversion rates. Supported authentication schemes include Mastercard Identity Check, Visa Secure, and American Express SafeKey.

Authentication within the mobile SDKs is limited to 3DS2 only. If 3DS2 is not available, the authentication will not proceed. However, you can still proceed with the payment if Simplify recommends you to do so.

When you perform EMV 3DS authentication (i.e. verify the identity of a cardholder) in a mobile app, the embedded 3DS SDK collects device metrics to send to Simplify along with your transaction information.

To increase the likelihood of the authentication being successful, provide as much information about the payer and the transaction as possible. This additional information can be added to your SimplifyMap object and submitted when you createCardToken. Name of cardholder Optional
card.number Card Number Required
card.securityCode Card CVV or CVC Required
card.expiry.month Card expiry month Required
card.expiry.year Card expiry year Required
card.addressLine1 Address Information Optional
card.addressLine2 Address Information Optional
card.addressZip Address Information Optional
card.addressState Address Information Optional
card.addressCountry Address Information Optional

These metrics help the system determine how/if to authenticate the cardholder. During authentication, the user can expect to experience one of two auth flows:

1. Frictionless: The ACS has collected enough information about the cardholder to authenticate them. No other action is needed by the user.

2. Challenge: The ACS requires the cardholder complete an additional authentication step (enter a onetime- password, login to their issuing bank, etc.) The embedded 3DS SDK handles displaying a native device interface for this challenge. The UI for these screens can be customized by passing UICustomization params into the Simplify SDK during initialization

3. Create a Card Token

To be able to create a payment for your goods or services you will first need to create a one time use card token. There are several pieces of information you will need to supply.

Card Information

Using an existing Session, you may pass card information directly to the Gateway:

// The SimplifyMap object provides support for building a nested map
structure using key-based dot(.) notation.
// Each parameter is similarly defined in your online integration guide.
var card = SimplifyMap()
card.number.value = cardNumber
card.card.securityCode.value = cvv
card.card.expiry.month.value = expiryMM
card.card.expiry.year.value = expiryYY

3D Secure Information

Using an existing Session, you may pass card information directly to the Gateway:

var threeDSData = SimplifyMap()
threeDSData.amount.value = 1500
threeDSData.currency.value = "ZAR" // Currency code (ISO-4217). AUD, EUR,
USD etc. Must match the currency associated with your account.
threeDSData.description.value = "Description"

Create the Token

This is done in the SDK by calling createCardToken with the information collected above. This should be done from the a View Controller. You will need to pass in a reference to the current navigation controller. This is needed for situations where a customer needs to be authenticated & a challenge flow is presented.

card: "Card Information",
secure3DRequestData: "Secure 3D Request Data",
navigationController: UINavigationController)

Note: Async/Await & Completion Handlers are provided in the SDK. You can use the implementation that best suits your mobile application architecture.

Interpreting the Response

The createCardToken method will return a SimplifyResult object containing important information about the outcome, as well as what actions were performed during the operation.

The most important field to consume is response.recommendation. It may contain the value proceed or doNotProceed. You may interpret proceed as "OK to continue with a payment or authorization". A value of doNotProceed would indicate that something failed during the authentication operation, or the payer was flagged as high risk.

The SimplifyResult object also contains a token field. This token can be used to submit a payment to simplify if the response.recommendation value is proceed.

SimplifySDK.shared.createCardToken(card: card, secure3DRequestData:
threeDSData, navigationController: UINavigationController(), completion: {
(response) in
switch response.recommendation {
case .doNotProceed:
// handle error
case .proceed:
// handle success / process payment
if let error = response.error {

If the authentication failed you can examine the response.error for more information about the cause.

Additional Information

Device and Simulator Builds

The Gateway SDK is released with 2 builds, a “device” version and a “simulator” version.

Bitcode can only be enabled for binaries that DO NOT support x86_64. Customers are likely to prefer the device version of SDK at release time, so they can enable bitcode in their apps which allows the app to have a smaller footprint on a userʼs device.

However, while developing, many developers prefer to use a simulator, so the x86_64 architecture is necessary. Additionally, during development, the app footprint is typically not a big concern. Gateway releases both bitcode-enabled (“Device”) and bitcode-disabled (“Simulator”) versions of the SDK to allow our customers to choose which they want to work with in any given scenario.

It is important to emphasize that the functionality and interface is exactly the same

See The Apple documentation for more.