📘

Current Version: 2.1.0

Tap to Pay on Android lets users accept in-person contactless payments with compatible NFC-equipped Android devices. Tap to Pay on Android includes support for Visa, Mastercard, American Express contactless cards and NFC-based mobile wallets (Apple Pay, Google Pay, and Samsung Pay). To use Tap To Pay on Android, your app must use the latest version of the EverCommerce Payments SDK and Android Stripe Terminal SDK version 3.2.1. Please contact our partner team at [email protected] or directly reach out to your Integrated Partner Manager for information about adding Tap To Pay to your Android app.

👍

The information provided on this page is limited to support for Tap To Pay on Android. For information on other SDK methods, delegates, and events see the ECP - Android Framework documentation.

🚧

Supported Android Devices

Android devices must meet all of the following criteria to be used with Android Tap To Pay:

• Contains functioning NFC antenna and chipset
• Isn’t rooted and device bootloader is locked and unchanged
• Runs a current version of Android (Android 11 or above)
• Uses Google Mobile Services
• Has a hardware backed keystore
• Supports generating key pairs using a variety of key algorithms, including RSA and AES from the Android keystore
• A stable connection to the internet

Device emulators are not supported for Tap To Pay. Recommended devices are the Samsung Galaxy S22 or Samsung Galaxy A12.

Add Tap To Pay To Your SDK Integration

Setup Android SDK

Your app must setup the Android ECP - Android Framework as specified here . Ensure you are on the latest version of dependency requirements. For Android, currently the latest version of dependency requirements is

implementation 'com.stripe:stripeterminal-localmobile:3.2.1'
implementation 'com.stripe:stripeterminal-core:3.2.1'
implementation 'androidx.appcompat:appcompat:1.4.1'
implementation 'com.android.volley:volley:1.2.1'
implementation 'com.google.code.gson:gson:2.8.9'
implementation files('../libs/EverCommercePaymentsAndroidSdk-release.aar')

The EverCommercePaymentsAndroidSdk-release.aar must be the latest version of the SDK designed to work with Tap To Pay.

Debuggable Security Setup (Required for Tap To Pay)

Using Tap To Pay on Android does not support debuggable applications for security and compliance reasons. In order to have your Tap To Pay device work your application must not be debuggable. If you will use bluetooth functionality only, in development environments you can continue to have a debuggable application.

Here is a sample of one way to make your app not debuggable:

build.gradle for app (see debuggable setting to false):

    buildTypes {

        debug {
            debuggable false
        }
        release {
            minifyEnabled false
            debuggable false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    buildToolsVersion '31.0.0'
}

AndroidManifest.xml (see debuggable set to false and tools:ignore="HardcodedDebugMode")

    <application
        android:name=".MyApplication"
        android:debuggable="false"
        android:allowBackup="true"
        android:extractNativeLibs="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.TestApp"
        tools:ignore="HardcodedDebugMode">

Permissions

Our Android Stripe SDK requires various permissions for use.

The following permissions should be declared in AndroidManifest.xml:

<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.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

The following permissions should be requested in code to use alongside our Shared ECP SDK:

ACCESS_FINE_LOCATION
ACCESS_COARSE_LOCATION
BLUETOOTH_CONNECT
BLUETOOTH_SCAN

Before initializing and attempting to use our Shared ECPSdk, make sure the permissions listed below are requested in code.

Example below for requesting permissions in code.

 ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION,
 Manifest.permission.ACCESS_COARSE_LOCATION,  Manifest.permission.BLUETOOTH_CONNECT,
 Manifest.permission.BLUETOOTH_SCAN}, 1);

You will also want to verify that your app user grants the permissions - the SDK will have issues functioning without the necessary permissions. One way to do this is to override the onRequestPermissionsResult method in your app and check the permission result. See sample code below (note: you will want to customize for your own individual app's needs):

Java

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);

    for (int i : grantResults) {
        if (i != 0) {
            Toast.makeText(MainActivity.this, "Not all permissions granted.  You may need to check your permissions", Toast.LENGTH_LONG).show();
        }
    }
// more code if needed here
}

🚧

The SDK needs to know where payments occur. If we can't determine the location of a device, payments may become disabled until location access is functioning again. Please ensure users of your app are always allowing location access.

Make a Payment With Tap To Pay

Initialize the SDK

Once your app has incorporated the latest dependencies, your app must initialize the SDK.

Configure SDK to Discover Tap To Pay

By default, the SDK is configured to discover only Bluetooth devices. To use Tap To Pay, your app must call the method Configure Reader Types in the SDK and include ECPSdkReaderConfigType.TapToPay in the set of ECPSdkReaderConfigType. Note Configure Reader Types must be called after the SDK is initialized. Once your configured reader types includes tap to pay, your app can proceed to discover and connect to a compatible Tap To Pay device.

Discover and Connect to a Tap To Pay Device

After adding Tap To Pay to the configured readers, your app can call Discover Devices. If a Tap To Pay Device is found, your app can call Connect Device to attempt to connect to the Tap To Pay device. If your app has configured the SDK to discover both Tap To Pay and Bluetooth, then the call to discover devices may return a list that includes both types and devices. In this case, your app must choose which device to connect to. A Tap To Pay ECPDevice returned from a call to discover devices will have an id_number of "Android Tap To Pay".

Make a Payment With Tap To Pay

With the SDK connected to a Tap To Pay device, your app may proceed to call Make Sale. Your app will need to collect the necessary information to create the ECPPaymentParameters and pass this into the call to make sale. After make sale is called, the SDK will take control of the device's display and provide the user with instructions to tap their card so the SDK may collect the payment method details. Once this process completes (or is cancelled from payment screen), control of the display will return to your app and the completion handler for make sale will provide information regarding the payment.

ECPSdkReaderConfigType (enum)

Enum which will be used to configure which types of devices the SDK will discover. ECPSdkReaderConfigType can be used to construct the HashSet to be passed in to Configure Reader Types. The following values can be used for ECPSdkReaderConfigType:
BLUETOOTH
TAPTOPAY

These values are accessible when using our Shared ECP SDK. See sample code below:

HashSet<ECPSdkReaderConfigType> selectedReaderTypes = new HashSet<>();
selectedReaderTypes.add(ECPSdkReaderConfigType.BLUETOOTH);
selectedReaderTypes.add(ECPSdkReaderConfigType.TAPTOPAY);

Configure Reader Types

Sets the type of devices that will be configured by the SDK. This method must be called after the SDK is initialized. If this method is not called, the default configuration is set to discover only bluetooth devices. If the set of configuredReaderTypes passed into the method is null or empty, an error will be returned. Upon successfully configuring the specified reader types, the completion handler will return isReaderTypesConfigured = true, the successfully configured set of configuredReaderTypes, and a null error message. Upon any sort of failure the SDKs set of configuredReaderTypes will remain unmodified. Only when isReaderTypesConfigured = true will the SDK modify configuredReaderTypes.

Note: If you attempt to configure Tap To Pay, this method includes some validation to ensure your device is compatible for Tap to Pay. If the device being used is not compatible with Tap To Pay, the callback will contain an ECPSdkCallbackError with a message indicating that your device cannot be used with TapToPay, and isReaderTypesConfigured will be false.

void configureReaderTypes(HashSet<ECPSdkReaderConfigType> configuredReaderTypes, ConfiguredReadersCallback configuredReadersCallback);

Example Implementation:

HashSet<ECPSdkReaderConfigType> selectedReaderTypes = new HashSet<>();
selectedReaderTypes.add(ECPSdkReaderConfigType.BLUETOOTH);
selectedReaderTypes.add(ECPSdkReaderConfigType.TAPTOPAY);

        _ecpSdk.configureReaderTypes(selectedReaderTypes, new ConfiguredReadersCallback() {
            @Override
            public void onComplete(boolean isReaderTypesConfigured, HashSet<ECPSdkReaderConfigType> hashSet, ECPSdkCallbackError ecpSdkCallbackError) {
                runOnUiThread(new Runnable() {
                    @Override
                    public void run() {
                        String displayMessage;
                        if(isReaderTypesConfigured)
                        {
                            displayMessage = "successfully configured reader types: " + createStringFromHashSet(hashSet);
                        }
                        else
                        {
                            displayMessage = "failed to configure reader types: " + ecpSdkCallbackError.errorDescription;
                        }
                        responseView.setText(displayMessage);
                    }
                });
            }
        });

Get Configured Reader Types

Returns a HashSet containing the types of Readers the SDK is configured for.

HashSet<ECPSdkReaderConfigType> getConfiguredReaderTypes();

Example Implementation:

HashSet<ECPSdkReaderConfigType> configTypes = _ecpSdk.getConfiguredReaderTypes();

Delegates / Listeners / Events

Android Stripe Tap To Pay will use the same Delegates / Listeners / Events as a Bluetooth device. The primary difference is that Tap To Pay will take control of the device display and provide the user with instructions to complete the payment. Do not interfere with the Tap To Pay UI and allow the Tap To Pay UI to flow until it returns to your screen.