Implement Tap to Phone Android SDK into your platform's Android application with five steps:

• Provide Rainforest your application information for Tap to Phone onboarding
• Install SDK dependencies
• Set up your application to use the SDK

Tap to phone onboarding

In order to take Android Tap to Phone payments, Rainforest must perform Android Tap to Phone onboarding on your behalf. Rainforest will need you to provide the following information for onboarding:

• App package name
• App signing key fingerprint
• App Google Play integrity keys

Package name

Your application's package name (example: com.rainforestpay.mobilepay)

Signing key fingerprint

You must generate a signing key and give us the fingerprint for the key. We only need the fingerprint, not the key itself.

# generate a new key
keytool -genkey -v -keystore my-signing-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-signing-key-alias
[provide keystore and key password when prompted]

# get fingerprint of key
keytool -exportcert -alias my-signing-key-alias -keystore my-signing-keystore.jks -storepass [password provided above] | \
    openssl sha256 -binary | \
    openssl base64

Google Play integrity keys

In order to verify your application and owner identity, we need to decrypt verification information from the Google Play Store.

Your app needs Play Integrity enabled:

1. Go to app dashboard in the Play console
2. Go to Test and release > App Integrity
3. Select Link cloud project
4. Follow prompts to link your project

Rainforest will need your Google Play Integrity keys to decrypt the Integrity Verification response:

1. Go to app dashboard in the Play console
2. Go to Test and release > App Integrity
3. Play Integrity API Settings > Classic requests
4. Choose option to "Manage and download my response encryption keys"
5. Follow directions to download the decryption and verifications
6. Provide Rainforest with the DECRYPTION_KEY and VERIFICATION_KEY values

Device Requirements

Certain features and criteria must be met to accept Tap to Phone payments on a device:

• Android 11.0 (API level 30) or higher operating system.
• Has NFC capabilities.
• Has location permissions enabled for host application.
• Has bluetooth permissions enabled for host application.
• Has identity security enabled on the device via face recognition, fingerprint or passcode.

Import SDK dependencies

Use our maven repos

Rainforest hosts its SDK in a Gitlab-provided Maven repository. Configure your application with the maven repo URL

# settings.gradle.kts

repositories {
    google()
    mavenCentral()
    # CloudCommerce AAR
    maven { url = uri("https://gitlab.com/api/v4/projects/77749278/packages/maven") }
    # Rainforest SDK AAR
    maven { url = uri("https://gitlab.com/api/v4/projects/77784047/packages/maven") }
}

Install Rainforest SDK dependencies

The Rainforest Tap UI utilizes the Jetpack Compose library. The dependency should be configured and enabled.

1. Add Compose at the project level
   Kotlin

   # build.gradle.kts
   
   plugins {
       alias(libs.plugins.android.application) apply false
       alias(libs.plugins.kotlin.android) apply false
       alias(libs.plugins.kotlin.compose) apply false
   }

2. Apply and enable Compose at the module level
   Kotlin

   # app/build.gradle.kts
   
   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.kotlin.compose)
   }
   
   ...
   
   android {
       buildFeatures {
           compose = true
       }
   }
   
   ...
   
   dependencies {
       implementation(platform(libs.androidx.compose.bom))
       implementation(libs.androidx.compose.ui)
       implementation(libs.androidx.compose.ui.graphics)
       implementation(libs.androidx.compose.ui.tooling.preview)
       implementation(libs.androidx.compose.material3)
   
       debugImplementation(libs.androidx.compose.ui.tooling)
   }

Add permissions

Add required permissions to app/src/main/AndroidManifest.xml:

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

Application setup

Application inheritance

Your application must inherit from TapToPhoneApplication. Inheriting from TapToPhoneApplication will require implementing the getPaymentsEnvironment function.

package com.rainforestpay.capyshopandroid

import android.util.Log
import com.rainforestpay.sdk.Environment
import com.rainforestpay.sdk.tap.TapToPhoneApplication

class ExampleApplication : TapToPhoneApplication() {
    override fun getPaymentsEnvironment(): Environment {
        return Environment.SANDBOX
    }
}

Session permissions

Create a session to grant the SDK permissions to process a payin with the permission group payment_sdk and pass the session_key into the Rainforest SDK.

"statements": [
  {
    "permissions": ["group#payment_sdk"],
    "constraints": {
      "merchant": {
        "merchant_id": "REPLACE_ME"
      }
    }
  }
]

Device registration

Each device with your platform's application must be registered as a Rainforest device registration.

Devices must be registered to a merchant in order to process payments, which is completed via the create device registration endpoint. You'll need to pass:

• registration_code: set to ANDROID_SDK
• merchant_id: the merchant to process payments on with the device
• device_name: the friendly name of the device, this will only appear in the Rainforest API and not in any Tap to Phone flows

{
    "registration_code": "ANDROID_SDK",
    "merchant_id": "sbx_mid_example",
    "device_name": "Example device"
}

The Device Registration ID will be utilized when presenting a payin and initiating the Tap to Phone payment flow through the Rainforest SDK. You should create a Rainforest Device Registration when your application is downloaded to the Android device and represents that specific Android device.

Each device that will utilize the Rainforest SDK for Tap to Phone must have it's own unique Rainforest Device Registration ID and cannot be shared across devices. Only one payin can be presented at a time on a Rainforest Device Registration.

Implementing the payment flow

1. Create a TapToPhone instance

To do this you will need:

• a session key with the correct permissions

• a device registration ID

  You will create this instance early in the application lifecycle. It will also need to be created when you have a new session key.

  val tapToPhone = RainforestPay.tapToPhone(context, environment, deviceRegistrationId, sessionKey)
  
  // where context is an instance of `android.app.Activity`

2. Prepare the device to take a tap payment

You will prepare the SDK at the start of your checkout flow

val prepareResult = tapToPhone.prepare()

3. Present payin using TapDialog

Presenting a payin requires:

• an initialized and prepared instance of the TapToPhone class
• a payin config ID

Render the payin when you're ready to start the tap transaction

TapCardDialog(
    activity = activity,
    ttp = ttp,
    payinConfigId = payinConfigId,
    deviceRegistrationId = deviceRegistrationId,
    onSuccess = { paymentResponse ->
        Log.d("TapUiDialog", "TapUiDialog onSuccess: $paymentResponse")

    },
    onError = { errMsg ->
        Log.d("TapUiDialog", "TapUiDialog onError: $errMsg")
    },
    onCancel = {
        Log.d("TapUiDialog", "TapUiDialog onCancel")
    }
)

SDK Reference

RainforestPay

Environment (enum)

SANDBOX · PRODUCTION

TapToPhoneInterface

Properties

Methods (all suspend unless noted)

TapUI (Composable)

Built-in Compose dialog. Requires ttp.isPrepared == true.

TapUI(
    activity: Activity,
    ttp: TapToPhoneInterface,
    payinConfigId: String,
    deviceRegistrationId: String,
    onSuccess: (PaymentResponse) -> Unit,
    onError: (Exception) -> Unit,
    onCancel: () -> Unit,
    autoDismissOnComplete: Boolean = false,   // skips post-tap result screens and returns control by to host app to display results
)

TtpEvent (sealed interface)

Events emitted in order during a normal transaction:

Collect from ttp.events to drive custom UI state.

PaymentResponse

data class PaymentResponse(
    val status: PaymentResponseStatus,  // SUCCESS | FAILURE
    val payin: PayinData,
)
// Convenience:
val isSuccess: Boolean
val isFailure: Boolean

data class PayinData(
    val payinId: String,
    val status: String,   // "PROCESSING" | "FAILED" | "CANCELED"
    val amount: Int,      // in cents
)

RainforestException

Thrown by TTP methods on failure.

class RainforestException(
    val code: RainforestErrorCode,
    message: String,
    cause: Throwable? = null,
)

TapToPhoneApplication (abstract)

Your Application class must extend this class and implement the getPaymentsEnvironment() method.

class MyApp : TapToPhoneApplication() {
    override fun getPaymentsEnvironment(): Environment = Environment.SANDBOX
}