Preparing for Development

Pre-requisites

Android Minimum Version

In order to support all required Card Schemes, the minimum supported Android version for Payment Device SDK for Android has been updated to 12 and is now enforced to at least 11.

The following minimum versions are also required:

• Gradle: 8.6
• Java: 17

Restrictions

Tap to Pay is an always online feature and cannot function without an internet connection at the point of interaction.

Offline transactions are not supported as they are restricted by payment industry's security standards for Tap to Pay transactions.

When using Tap to Pay in production developer options must be disabled and the device cannot be connected to a USB device due to MPoC security restrictions.

In cases where these restrictions are not met, attestation will fail and the appropriate errors are returned to the integrating app, these are detailed later in the document.

Geofencing Restrictions

Tap to Pay employs geofencing as a fraud prevention measure. To ensure compliance during development, the API key used for testing must be associated with a merchant account registered in the same location where you are developing your application.

Additionally, transaction processing is currently restricted to the following countries:

• United States (US)
• United Kingdom (UK)
• All EEA countries (including Romania, Ukraine, and Poland)
• Canada
• China
• Indonesia
• Brazil
• South Africa
• India
• Vietnam
• Philippines
• Mexico
• Argentina
• Israel

If you require support for additional countries, please contact your account manager.

Project Setup

Dependencies

Implementing Tap To Pay requires adding the Cloud Commerce SDK to your Android project. There are two Cloud Commerce binaries provided due to MPoC security requirements, it ensures your production build remains lean, secure, and compliant. A test aar allows for debugging and testing of integration during development.

In the Android release these can be found at:

• Test SDK libs/cloud-commerce-sdk-mtf-<version>.aar
• Production SDK libs/cloud-commerce-sdk-<version>.aar

To implement the Cloud Commerce SDK will require creating a new module for it. This module needs to contain the cloud commerce aar files and a build.gradle file. The gradle file wants to contain the following (depending on the aar you wish to implement):

configurations.maybeCreate("default")
artifacts.add("default",file("./cloud-commerce-sdk-mtf-<version>.aar"))

The settings.gradle file of the integrating application will also want to contain the lines, replacing <ModuleName> and <PathFromRepositoryRoot> with values of the new module containing the cloud-commerce-sdk:

include ':<ModuleName>'
project(':<ModuleName>').projectDir=new File('<PathFromRepositoryRoot>')

In addition the following projects must be implemented in the applications app level build.gradle file:

implementation project (":CloudCommerceSDK")

In your application should also implement the following dependencies:

implementation 'com.google.android.play:integrity:1.1.0'
implementation 'com.squareup.retrofit2:adapter-rxjava3:2.9.0'
implementation 'com.google.android.gms:play-services-location:21.0.1'
implementation 'com.squareup.okhttp3:logging-interceptor:4.4.0'
implementation 'io.reactivex.rxjava3:rxjava:3.0.0'
implementation 'io.reactivex.rxjava3:rxandroid:3.0.0'
implementation 'com.squareup.retrofit2:converter-scalars:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.google.code.gson:gson:2.8.6'
implementation 'commons-codec:commons-codec:1.11'
implementation 'com.squareup.okhttp3:okhttp-urlconnection:4.4.0'
implementation 'androidx.security:security-crypto:1.1.0-alpha06'
implementation 'com.google.android.gms:play-services-safetynet:17.0.0'
implementation 'org.slf4j:slf4j-api:1.7.30'
implementation fileTree(include: ['*.jar'], dir: 'libs')
implementation 'androidx.core:core-ktx:1.8.0'
implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.6.0'
implementation 'net.zetetic:android-database-sqlcipher:4.5.3@aar'
implementation 'androidx.sqlite:sqlite:2.0.1'
implementation 'com.jakewharton.timber:timber:4.7.1'

Please look at the Payment Device SDK for Android - API for Release Documentation supplied within the release bundle for a more detailed breakdown of required dependencies for running the Payment Device SDK.

There must be no reference to org.apache.http.legacy in any build.gradle file.

Additional Permission Requirements

During configuration the Payment Device SDK will perform a suite of security checks, including requiring the integrating application to be granted location permissions. The recommended permissions include:

Extending ChipDnaMobileSDK Application Class

To initialize the Payment Device SDK to allow Tap To Pay, it is required that the integrating application must contain an application class that extends ChipDnaApplication. This is due to MPoC requirements for the Tap To Pay solution. APIs exposed by Cloud Commerce SDK can only be consumed through their own backend environment which our ChipDnaApplication extends. It manages the initialization of the SDK instance to enable API consumption by the app module. In addition to this, it also performs security checks in the background and disables access to API further in case of any vulnerability detected.

The success of the SDK initialisation can be observed by the integrating app through the following override methods:

void onSDKInitializationSuccess()

void onSDKInitializationFailed(
    errorMessage: String?
)

It is required when implementing them to call the super of the methods.

The following is an example of a class extending the ChipDnaApplication.class.

open class DevApplication : ChipDnaApplication() {

    override fun onSDKInitializationSuccess() {
        // The following line is required when implementing this method
        super.onSDKInitializationSuccess()
        Log.d("ChipDnaApplication", "SDK Initialization Success")
    }

    override fun onSDKInitializationFailed(errorMessage: String?) {
        // The following line is required when implementing this method
        super.onSDKInitializationFailed(errorMessage)
        Log.e("ChipDnaApplication", "SDK Initialization Failed: $errorMessage")
        Toast.makeText(this, "Fail: $errorMessage", Toast.LENGTH_SHORT).show()
    }
}

The application class that extends ChipDnaApplication must also be included in the AndroidManifest.xml. The following example shows a section of an AndroidManifest.xml with the required change highlighted, the name of the class matching that of the example above.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29"/>
    <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE"/>

    <application
        android:name=".DevApplication"
        <!-- other application attributes -->
    >
        <!-- application components -->
    </application>
</manifest>

App Onboarding is also a prerequisite requirement in both production and test environments. Without the Tap to Pay feature will return an error. Refer to our section App Onboarding