The Littlepay Checkout Developer Hub

Welcome to the Littlepay Checkout developer hub. You'll find comprehensive guides and documentation to help you start working with Littlepay Checkout as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Android SDK

Littlepay Checkout SDK for Android

The Littlepay Checkout SDK is an online payment solution for Android applications.
It supports card payments (including secure card authentication supporting 3DS1 and 3DS2), PayPal and Google Pay™.

This document explains how to integrate the SDK into your project.

Download

Add Littlepay's repository url to your project and add the SDK dependency to your app configuration.

build.gradle

allprojects {
    repositories {
        ...
        maven { url "https://gitlab.com/api/v4/projects/25726570/packages/maven" }
}

app/build.gradle

implementation "com.littlepay.checkout:android-sdk:0.6.1"

Cardinal SDK Credentials

Littlepay's Checkout SDK is using Cardinal's 3DS SDK to perform 3DS conform card checkouts. Cardinal's repository is secured by username and password. Contact Cardinal to gain credentials and add your credentials to Gradle's repository configuration.

build.gradle

allprojects {
    repositories {
        ...
        maven {
            url "https://cardinalcommerce.bintray.com/android"
            credentials {
                username <INSERT CARDINAL CREDENTIALS USERNAME>
                password <INSERT CARDINAL CREDENTIALS PASSWORD>
            }
        }
    }
}

Checkout

Use checkout method to charge an order or subscription. Pass the client token you received by your backend and set up the user data with information about your customer.

// in your fragment/activity
val clientToken = myBackendService.getClientTokenForCheckout()
CheckoutSdk().checkout(
    this,
    clientToken,
    countryCode = "GB", // ISO 3166-1 alpha-2 country code where the transaction is processed   
    userData = myUserData // (optional) Information about the current checkout user
)

Google Pay™ requires the ISO 3166-1 alpha-2 country code where the transaction is processed. This is required for merchants based in European Economic Area (EEA) countries (see Google Pay™ docs).

Providing additional user data is not required but recommended since it will minimize the likelihood of 3DS identification challenges for card payments.

Google Pay™

Google Pay™ is already fully integrated into the checkout SDK. To understand how this integration is realised, checkout the official Google Pay™ documentations:

All merchants must adhere to the Google Pay™ APIs Acceptable Usage Policy and accept the terms defined in the Google Pay™ APIs Terms of Service.

Saved Card Payments

When paying with a card, the user has the option to tick the save checkbox. The backend will then save the card details and shows the saved card as payment option. The user can delete saves cards through the app.

Managing Saved Cards

Use manageSavedCards method to view, add and remove cards to/from list of saved cards. Saved cards can be used during checkout.

// in your fragment/activity
val clientToken = myBackendService.getClientTokenForManagingSavedCards()
CheckoutSdk().manageSavedCards(
    this,
    clientToken
)

Retrieving Results

Checkouts and saved card managements return results in form of Activity results. To retrieve results you have to override onActivityResult in your Activity. To transform the parameters in a result object use CheckoutSdkResultHandler.resolve. If the result is of type CheckoutSdkResult.Error the object will contain an error that you can look up here

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    CheckoutSdkResultHandler.resolve(requestCode, resultCode, data) {
        when (result) {
            is CheckoutSdkResult.Success -> // checkout or card management finished successful
            is CheckoutSdkResult.Cancelled -> // checkout cancelled by user
            is CheckoutSdkResult.Error -> {
                // something went wrong - retrieving error type
                val errorType = result.error
            }
        }
    }
    super.onActivityResult(requestCode, resultCode, data)
}

Security Checks

The SDK will check for security issues every time you use it. By default the SDK will block payments or saved card management if:

  • The device is rooted.
  • The integrity of the Cardinal SDK has been ≠tampered with.
  • An emulator is being used to run the App.
  • A debugger is attached to the App.
  • The OS or the OS version is not supported by Cardinal.
  • The application is not installed from a trusted source.

You can turn off security checks when you initialise the SDK.

val sdk = CheckoutSdk(
    ignoreSecurityWarnings = true
)

TLS

Talking to Littlepay services requires at least TLS version v1.2. Android supports v1.2 from API 16 but by default it is disabled up to version 19. (see here) The Littlepay Android SDK has a build in mechanism to enable TLS when you use it.

Anyway if you run into problems you can try to activate v1.2 inside you app by using Google Play Services.

app/build.gradle

implementation "com.google.android.gms:play-services-safetynet:17.0.0"

In you project you are now able to activate TSL v1.2 by calling

ProviderInstaller.installIfNeeded(context)

or you use the extension function that comes with the SDK.

fun Context.isTslEnabled(): Boolean

Testing

Test cases, test cards and error types can be found in our shared documentation.

Card Payments

The Littlepay Android SDK supports 3DS1 and 3DS2. You can choose specific test card numbers to test card payments.

PayPal

To test payments with PayPal you need a PayPal sandbox account first. If you do not have one yet you can create one here.
When choosing PayPal as payment option you will be asked for the account credentials you created.

Google Pay™

To test payments with Google Pay you will need to have the Google Pay app installed on your phone/emulator and have at least one real card linked to it. When choosing Google Pay™, only Mastercard and Visa cards are supported. Your card will NOT be charged while using the sandbox environment.

Emulator Issues

To use the SDK on an emulator, you need to turn off security checks when you initialise the SDK.

val sdk = CheckoutSdk(
    ignoreSecurityWarnings = true
)

Updated about a month ago

Android SDK


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.