Follow the simple steps below and get started developing.

1. Add Android Framework


The Simplify SDK requires a minimum android SDK version of 23.

Note: We used Hilt for dependecy injection


This SDK is packaged as aar file. It should be copied inside your app level libs folder and added as a dependency in your app's build.gradle file.

1. From your Simplify Merchant Admin portal, download the latest version of the SDK in aar file format.

2. Copy this file and put it in libs directory of your Android project. (ex: ~/src/main/libs)

3. Add below lines to your project level build.gradle file.

// build.gradle
allprojects {
    repositories {
        flatDir {
            dirs 'libs'

4. In your app module's build.gradle file, include the Simplify SDK as a dependency

// app/build.gradle
implementation(name:'simplify-android', ext:'aar')

Hilt Dependencies

It's recommeded to use Hilt in your application and provide dependencies as below.

object AppModule {
    fun provideApplication(@ApplicationContext app: Context) :
    // your application name {
        return app as // your application name
fun provideNetworkInfo(@ApplicationContext app: Context) :
 NetworkInfoProvider {
    return app as NetworkInfoProvider

2. Collect Card Information

Setting API keys

Before it can be used, the Android SDK must implement NetworkInfoProvider. It's recommended this operation be performed in your custom Application class and override simplifyConfig like below

// CustomApplication.kt
class CustomApplication : Application(), NetworkInfoProvider {
    override fun attachBaseContext(base: Context?) {
    override var simplifyConfig: SimplifyConfig = SimplifyConfig(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.

lateinit var cardTokenApi: CardTokenApi

// call create card token

this: "activity instance",
card: "Card Information",
secure3DRequestData: "Secure 3D Request Data")

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.

cardTokenApi.createCardToken(this, card, secure3DRequestData) { response ->
        when (response.recommendation) {
        PROCEED -> // handle success / process payment
        DO_NOT_PROCEED -> // handle error
        else -> throw IllegalStateException("message")

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