FILTER BY TAG

Getting Started with the Tap to Pay on Android Solution

Use the information in this section to get started with integrating the Tap to Pay on Android Solution. When the integration is completed, your application will be ready to start processing payments. For more information, see Tap to Pay on Android Payment Services.

Configuring the Tap to Pay on Android SDK

Use the information in this section to configure the Tap to Pay on Android SDK.

Configure the Project
settings.gradle
File

Follow this step to configure your project's
settings.gradle
file.
  1. Add the repository to your project's
    settings.gradle
    file.
    dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { mavenCentral() google() exclusiveContent { forRepository { maven { setUrl("https://repo.visa.com/mpos-releases/") } } filter { includeGroup("io.payworks") } } } }

Configure the Project
build.gradle
File

Follow this step to configure your project's
build.gradle
file.
  1. Add the Kotlin Gradle plug-in, which is required to use this solution. Note that Kotlin version 2.1 or later and Android Gradle version 8.2 or later are required.
    plugins { id("com.android.application") version "8.2.0" apply false id("org.jetbrains.kotlin.android") version "2.1.0" apply false }

Configure the Module
build.gradle
File

Follow these steps to configure your module
build.gradle
file.
  1. In the Android section, add these exclusion rules to your module's
    build.gradle
    file.
    android { ... packaging { resources { excludes.add("META-INF/*") excludes.add("LICENSE.txt") excludes.add("asm-license.txt") } } }
  2. In order for the app to support Java 17 features, you must set the compatibility levels.
    android { ... compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } kotlinOptions { jvmTarget = "17" } }
  3. The Tap to Pay on Android Solution library publishes a release build type only. The debug build type is not available, so set the
    matchingFallbacks
    field value to
    release
    .
    android { ... buildTypes { ... debug { matchingFallbacks.apply { clear() add("release") } } } }
  4. IMPORTANT
    Stay current with the latest SDK. The SDK repository is continuously updated to make available the six latest versions. When a new version is released, the oldest is removed and can no longer be used for new application builds. Establish a regular process for updating to the newest available SDK version to avoid potential build failures and to ensure that your application runs with the latest features, performance enhancements, and security updates.
    Add the required Default UI and Tap to Pay on Android libraries to the Dependencies section of your module's
    build.gradle
    file.
    dependencies { ... // This is the Default UI dependency implementation("io.payworks:paybutton-android:2.110.0") // This is the Tap to Pay dependency implementation("io.payworks:mpos.android.taptophone:2.110.0") }

Update the
AndroidManifest.xml
File

To support a large heap size and ensure the necessary permissions for the Default UI, update your
AndroidManifest.xml
file. Enabling a larger heap is essential for scenarios where terminal updates require the handling and transfer of large volumes of data.
WARNING
Do not enable automatic backup in your app's
AndroidManifest
file. The Tap to Pay on Android SDK uses the Android Keystore to install and store cryptographic keys in your app. Using automatic backup restores the default encryption preferences and causes a functionality error in the Tap to Pay on Android SDK.
Follow these steps to update your
AndroidManifest.xml
file:
  1. Set the
    android:allowBackup
    attribute to
    false
    and the
    android:largeHeap
    attribute to
    true
    .
    <application ... android:allowBackup="false" android:largeHeap="true" > ... </application>
  2. Enable the needed permissions for the Default UI.
    <manifest ... > ... <!-- Needed for Default UI ! --> <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> <uses-permission android:name="android.permission.READ_PHONE_STATE"/> ... </manifest>

Configure ProGuard Rules to Enable Obfuscation

Follow these steps to configure ProGuard rules that enable obfuscation.
  1. To enable obfuscation for any of your build types, define the setting in the relevant
    build.gradle
    file for your app.
    buildTypes { release { isMinifyEnabled = true proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro") } }
  2. If you are using ProGuard as an obfuscation tool in your app, add these rules to the
    proguard-rules.pro
    file.
    # OkHttp -keepattributes Signature -keepattributes *Annotation* -dontwarn com.squareup.okhttp.** -keep class com.squareup.okhttp.* { *; } -dontwarn okio.** # Acceptance Devices -keep class io.mpos.** { *; } -dontwarn io.mpos.** -keep class com.visa.vac.tc.** {*;} -keep class com.nimbusds.jose.** {*;} -keep class org.bouncycastle.** {*;} -keep class retrofit2.** { *; } -keep interface retrofit2.** { *; } -keep class com.visa.auth.** { *; } -dontwarn com.visa.auth.** -keep class androidx.** { *; } # Visa Sensory Branding -keep class com.visa.SensoryBrandingView # Mastercard Sonic Branding -keep class com.mastercard.sonic.BuildConfig {*;}

Installing the Tap to Pay Ready App

The Tap to Pay Ready app must be installed on your Android device to support PCI-compliant payment processing. This app is a core component of the PCI-Certified MPoC Solution. For more information, see PCI MPoC Standard Compliance and Transaction Workflow for the PCI-Certified MPoC Solution.

Install the Tap to Pay Ready App

Use one of these options to install the Tap to Pay Ready App on your device:
  • Click this Google Play store link to install the app directly on your Android device. No additional set up is required.
  • Download the app when prompted during device enrollment. For more information, see Enroll a Device.

Generating a Secret Key for an Existing Merchant ID

You must enter a secret key and MID in the
mposUi
 instance that you create. Use the information in this section to generate a secret key for an existing merchant ID (MID) through the
Business Center
or by submitting a REST API request.
For more information about the
mposUi
 instance, see Creating an mposUI Instance.

Generate a Secret Key for an Existing Merchant ID in the Business Center

You can generate an secret key for an existing merchant ID (MID) in the
Business Center
. Enter these values in the
mposUi
 instance that you create. For more information, see Creating an mposUI Instance.
Follow these steps to generate a secret key for an existing MID in the
Business Center
:
  1. In the
    Business Center
    , go to the left navigation panel and choose
    Payment Configuration
    >
    Key Management
    . The Key Management page appears.
  2. From the Merchant drop-down list, choose the merchant ID for which you want to generate a secret key.
  3. Click
    Generate Key
    .
  4. In the Recommended Key Types list, scroll down and choose
    Acceptance Devices Secret Key
    .
  5. Click
    Generate Key
    . The Key Generation page appears.
  6. Click
    Generate Key
    . Your MID and secret key appear on the page.
  7. Click the
    Copy
    or
    Download
    icon to obtain the MID and secret key.

    ADDITIONAL INFORMATION

    IMPORTANT
    If you choose to copy the secret key information instead of downloading it, be sure to save it locally. After you leave the
    Business Center
    Key Generation page, you will not be able to retrieve the same secret key again. To obtain a new key, you must restart the key generation process.

Generate a Secret Key for an Existing Merchant ID Using a REST API Request

You can submit a REST API request to generate a secret key for an existing merchant ID (MID). Enter these values in the
mposUi
 instance you create. For more information, see Creating an mposUI Instance.
You must authenticate each request that you send to a
Cybersource
API. In order to authenticate an API request, you can use a REST shared secret key or a REST certificate. For more information about authentication requirements, see .

Endpoints:

Test:
POST
https://apitest.cybersource.com
/kms/v2/keys-sym-pos
Production:
POST
https://api.cybersource.com
/kms/v2/keys-sym-pos

Required Fields for Generating a Secret Key for an Existing Merchant ID Using a REST API Request

keyInformation.organizationId

REST Example: Generating a Secret Key for an Existing Merchant ID Using a REST API Request

Request
{ "keyInformation": [ { "organizationId": "transacting_MID" } ] }
Response to a Successful Request
{ "submitTimeUtc": "2023-08-07T13:07:17Z", "status": "ACCEPTED", "keyInformation": [ { "organizationId": "transacting_MID", "externalOrganizationId": "MerchantId", "key": "SecretKey", "keyId": "af922a42-6d2c-41fd-92f7-09d908647de4", "status": "ACTIVE", "expirationDate": "2033-08-07T13:07:17Z" } ] }

Creating an mposUI Instance

Use the information in this section to create and configure an
mposUI
 instance.

Create an
mposUI
Instance

Before starting this procedure, you must have a secret key and a merchant ID (MID) values to enter in to your
mposUI
 instance. For more information, see Generating a Secret Key for an Existing Merchant ID.
Create an
mposUI
 instance to access the functionality of the Tap to Pay on Android SDK.
Follow these steps to create an
mposUI
 instance.
  1. Create an
    mposUI
    instance using the
    create
    function.
  2. Set the
    merchantId
    field value to the merchant ID that you obtained.
  3. Set the
    merchantSecret
    field value to the secret key that you obtained.
  4. Specify the environment by setting the
    providerMode
    field value to
    TEST
    or to
    LIVE
    • Use the
      ProviderMode.TEST
      setting to test your integration without charging a real payment card. Use the merchant ID and secret key you obtained from the test environment.
    • Use the
      ProviderMode.LIVE
      setting to process live transactions. Use the merchant ID and secret key you obtained from the production environment.
    val mposUi = MposUi.create( providerMode = ProviderMode.LIVE, // ProviderMode.TEST merchantId = "MerchantId", merchantSecret = "SecretKey" )

Configure an mposUI Instance

To use the
mposUI
instance with the Tap to Pay on Android SDK, you must configure the
mposUI
instance by creating a
UiConfiguration
 instance.

Create a
UiConfiguration
Instance

Use a
UiConfiguration
 instance to configure the UI functionality of the Tap to Pay on Android SDK.
You can configure these parameters in the
UiConfiguration
 instance that you create:
  • Configure the accessory as Tap to Phone.
  • Configure these Summary screen features:
    • Refund a transaction (
      REFUND_TRANSACTION
      ).
    • Send a receipt by email (
      SEND_RECEIPT_VIA_EMAIL
      ).
    • Capture a transaction (
      CAPTURE_TRANSACTION
      ).
    • Retry a failed transaction (
      RETRY_TRANSACTION
      ).
    • Increment a transaction (
      INCREMENT_TRANSACTION
      ).
  • Configure the Summary screen so that it can be skipped (
    SKIP_SUMMARY_SCREEN
    ) or so that it closes after 5 seconds (
    CLOSE_AFTER_TIMEOUT
    ). The default setting is to show the Summary screen.
  • Configure the signature capture so that it prints on the paper receipt (
    ON_RECEIPT
    ) or is skipped (
    NONE
    ). The default setting is on-screen signature capture.
Follow this step to create the
UiConfiguration
 instance in your app:
  1. Create and configure the
    UiConfiguration
     instance.
    mposUi.configuration = UiConfiguration( terminalParameters = AccessoryParameters.Builder(AccessoryFamily.TAP_TO_PHONE).integrated().build(), summaryFeatures = setOf( SummaryFeature.REFUND_TRANSACTION, SummaryFeature.SEND_RECEIPT_VIA_EMAIL, SummaryFeature.CAPTURE_TRANSACTION, SummaryFeature.RETRY_TRANSACTION, SummaryFeature.INCREMENT_TRANSACTION ) // Use this to skip the summary screen // resultDisplayBehavior = UiConfiguration.ResultDisplayBehavior.SKIP_SUMMARY_SCREEN, // Use this to set signature capture to be on paper receipt // signatureCapture = SignatureCapture.ON_RECEIPT, )

Create a
TapToPhoneConfiguration
Instance

Create a
TapToPhoneConfiguration
 instance to configure the device enrollment process of the Tap to Pay on Android SDK.
You can configure these parameters in the
TapToPhoneConfiguration
instance that you create:
  • Configure the enrollment process to prompt the merchant to enter the serial number of a previously enrolled device (
    MANUAL_INPUT
    ). The default setting is to show a list of previously enrolled devices and prompt the merchant to select a device from the list (
    DEVICE_LIST
    ).
  • Configure the Serial Number Confirmation screen to be skipped (
    SKIP
    ). The default setting is to show the screen (
    SHOW_WITH_SERIAL_NUMBER
    ).
Follow this step to create and configure the
TapToPhoneConfiguration
instance in your app:
  1. Create and configure the instance.
    mposUi.tapToPhone.tapToPhoneConfiguration = TapToPhoneConfiguration( serialNumberInputMethod = SerialNumberInputMethod.DEVICE_LIST, confirmationScreenOption = ConfirmationScreenOption.SHOW_WITH_SERIAL_NUMBER )

Customizing the Default User Interface

Use the information in this section to customize the Default UI so that it matches your brand’s visual identity. The included screenshots highlight several style elements with labels for reference. Note that not all available style elements are shown. A detailed description of the style elements follows the screenshots.

Figure:

Tap to Pay on Android Default UI Style Elements
Example 1, Tap to Pay on Android Default UI style elements showing icons, labeled
          buttons, colors, and text

Figure:

Tap to Pay on Android Default UI Style Elements
Example 2, Tap to Pay on Android Default UI style elements showing icons, labeled
          buttons, colors, and text

Figure:

Tap to Pay on Android Default UI Style Elements
Example 3, Tap to Pay on Android Default UI style elements showing icons, labeled
            buttons, colors, and text
This list describes the style elements that you can customize in the Default UI:
animationStrokeColor
Stroke or outline color for animations.
approvedStateColor
Indicator color that appears for the approved transaction badge and animation.
cardPresentAnimationStrokeColor
Overrides the
animationStrokeColor
style element in the card reader drawing on present-card animations. By default, this element is the same color as the
animationStrokeColor
style element.
colorControlActivated
Color applied to switch controls in their active state.
colorOnPrimary
Primary color that appears for the filled button text and animation details.
colorOnSurface
Color for text that appears over the content view, transaction status badges text, and outlined button stroke.
colorPrimary
Primary color that appears for the filled buttons and animations.
colorSurface
Background color that appears for the content view.
colorSurfaceOnSurface
Background color for displayed lists such as transaction history.
contactlessStateActiveColor
Active indicator color that appears when the contactless interface is ready or when a payment card is tapped on the device.
contactlessStateErrorColor
Error indicator color that appears when a problem occurs when the device attempts to read a card on the contactless interface.
contactlessStateInactiveColor
Inactive indicator color that appears when the contactless interface is not active.
declinedErrorStateColor
Indicator color that appears for these elements:
  • Declined transaction badges and animation
  • Error transaction badges and animation
  • Error dialog boxes
  • Input field error messages
notificationColor
Alert notification color that appears with
Poor connection
and
Low battery
notifications. The default color is yellow.
preAuthorizedStateColor
Indicator color that appears for the pre-authorized transaction badge.
smallComponentCornerSize
Defines the corner radius of the buttons and transaction status badge. Set this element to
0dp
for square corners,
4dp
for slightly square corners (default), or
32dp
for round corners.
toolBarLogo
Logo that appears during transaction processing. The image must be rectangular, have the minimum dimensions of 144 x 36 pixels, and a 4:1 ratio.

Customize Style Elements Using a Theme

Follow these steps to customize the Default UI style elements.
  1. Introduce a new theme to your application that includes the
    Theme.PayButton2
    theme as a parent theme.
    <!-- Paybutton theme --> <style name="Theme.AppTheme.SampleTheme" parent="Theme.PayButton2"> <!-- Text color --> <item name="colorOnSurface">@color/black</item> <!-- Background color --> <item name="colorSurface">@color/white</item> <!-- Contactless indicators --> <item name="contactlessStateActiveColor">@color/dui_green</item> <item name="contactlessStateInactiveColor">@color/dui_light_gray2</item> <item name="contactlessStateErrorColor">@color/dui_red</item> <!-- Transaction status --> <item name="approvedStateColor">@color/dui_green</item> <item name="declinedErrorStateColor">@color/dui_red</item> <!-- Also used for error messages and dialogs --> <item name="preAuthorizedStateColor">@color/dui_dark_gray</item> <!-- Filled buttons and animations primary color --> <item name="colorPrimary">@color/dui_blue</item> <!-- Used over the primary color for text on filled buttons and details on animations --> <item name="colorOnPrimary">@color/dui_white</item> <!-- Corner radius for the buttons and transaction status badges --> <item name="smallComponentCornerSize">4dp</item> <!-- Company logo --> <item name="toolBarLogo">@drawable/logo_140x36</item> <!-- Stroke color for icons and animations --> <item name="animationStrokeColor">@color/dui_black</item> </style>
  2. Call one of these methods to set the theme:
    mposUi.themeRes = R.style.Theme_AppTheme_SampleTheme

Customize Style Elements Using a
UiConfiguration
Instance

Use this customization feature to dynamically change some Default UI style elements while the app is in use. These style elements can be customized using a
UiConfiguration
instance:
  • toolbarLogo
  • colorScheme
    (and its sub-elements)
  • cornerRadius
Follow this step to customize Default User Interface style elements using a
UiConfiguration
instance:
  1. Create the
    UiConfiguration
     instance.
    mposUi.configuration = UiConfiguration( // other UiConfiguration parameters toolbarLogo = "....", colorScheme = UiConfiguration.ColorScheme( colorPrimary = 0xFF1A1F71, colorOnPrimary = 0xFFFFFFFF, colorSurface = 0xFFFFFFFF, colorOnSurface = 0xFF1C1B1B, ), cornerRadius = UiConfiguration.CornerRadius.ROUND )

Enable Dark Mode in the Default User Interface

When the payment device is set to dark mode, the Default UI payment screens automatically adjust to display darker, high-contrast colors compared to the default light mode settings. This feature is particularly useful in low-light environments such as restaurants and bars.
By default, the dark mode background color is dark gray (
#121212
). To customize the background to pure black (
#000000
), define a new
Theme.PayButton2
theme in the
values-night
resource folder.
For more information about the dark mode setting on Android devices, see the Android documentation.
Follow this step to change dark mode behavior:
  1. Use this Android method to enforce light or dark mode across your entire application and the Default UI, regardless of the system setting on the device. This example enforces night mode.
    AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)

Enabling Device Enrollment

Use the information in this section to enable device enrollment and view the device enrollment result in the Tap to Pay on Android SDK. The enrollment workflow guides you through the device enrollment activity.

Enroll a Device

Before starting the device enrollment process, make sure the Tap to Pay Ready app is installed on the Android device. Download the app using this Google Play Store link. If the app is not installed before device enrollment, you will be prompted to install it during the enrollment process. To learn more about the Tap to Pay Ready app, see PCI MPoC Standard Compliance.
Use the information in this section to enroll a device using the
enrollDevice
activity. This activity presents a merchant-facing UI that enables users to enroll a new device or a previously enrolled device by selecting or entering the device’s serial number.
Follow this step to enroll a device.
  1. Use the
    enrollDevice
    activity to enroll the device.
    val mposUi: MposUi = ... mposUi.tapToPhone.enrollDevice(activity, requestCode) ... override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { if (EnrollResultIntent.isEnrollmentSuccessful(resultCode, data)) { onDeviceEnrolled() } super.onActivityResult(requestCode, resultCode, data) }

    Step Result

    The
    enroll
    activity returns the result Intent.

Enroll a Previously Enrolled Device

Use the information in this section to enroll a previously enrolled device by using the
reEnrollDevice
activity. This activity enables you to perform device re-enrollment through the SDK by supplying a stored serial number. This streamlined workflow eliminates the need for the merchant to manually select or enter the serial number during re-enrollment.
  1. Use the
    reEnrollDevice
    activity to enroll the previously enrolled device.
    val mposUi: MposUi = ... mposUi.tapToPhone.reEnrollDevice(activity, serialNumber, requestCode) ... override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { if (EnrollResultIntent.isEnrollmentSuccessful(resultCode, data)) { onDeviceEnrolled() } super.onActivityResult(requestCode, resultCode, data) }

    Step Result

    The
    enroll
    activity returns the result
    Intent
    .

View the Device Enrollment Result

After completing device enrollment, use the
enroll
activity or
isDeviceEnrolled
function to view the device enrollment result.
The
enroll
activity returns the result
Intent
when the device enrollment process is successful. This example shows the information that is returned in the result
Intent
:
RESULT_CODE: EnrollResultIntent.ENROLMENT_RESULT_CODE (3489523) EXTRA: EnrollResultIntent.ENROLMENT_RESULT_EXTRA (enrolmentResult = deviceEnrolled) EXTRA: EnrollResultIntent.ENROLLMENT_RESULT_EXTRA_SERIAL_NUMBER (serialNumber)
The
isDeviceEnrolled
function returns a
true
value when the device is enrolled or a
false
value when not. This example shows how to use the function:
enrollmentstatus = isDeviceEnrolled()