On This Page
Acceptance Devices | Tap to Pay on Android Solution Integration Guide
This section describes how to use this guide and where to find further information.
Audience and Purpose
This guide is written for application developers who want to integrate the Acceptance
Devices | Tap to Pay on Android software development kit (SDK) into their apps and to
process contactless transactions on mobile devices.
Integrating this SDK requires software development skills and the understanding of
contactless payments on near-field communication (NFC)-enabled, commercial, off-the-shelf
(COTS) mobile devices. You must write code that uses the SDK to integrate the Acceptance
Devices | Tap to Pay on Android payment service into your existing payment system.
Conventions
These statements appear in this document:
IMPORTANT
An
Important
statement contains information essential to
successfully completing a task or learning a concept.WARNING
A
Warning
contains information or instructions, which, if not
heeded, can result in a security risk, irreversible loss of data, or significant cost in
time or revenue or both.Customer Support
For support information about any service, visit the Support Center:
Recent Revisions to This Document
25.11.01
- Updated list of handheld, kiosk, and tablet devices in Payment Devices Supported by the Tap to Pay on Android Solution.
- Applied these updates to Create a UiConfiguration Instance:
- Removed Summary screen primary button configuration option.
- Updated code example in step 1.
- Added new SDK release and updated release version in code examples. See SDK Version 2.107.0 Release Notes.
25.10.01
- Revised and relocated these topics:
- Added new SDK release and updated release version in code examples. See SDK Version 2.106.0 Release Notes.
25.09.01
- Updated configuration parameters in Create a TapToPhoneConfiguration Instance.
- Added new SDK release and updated release version in code examples. See SDK Version 2.105.0 Release Notes.
25.08.01
- Added new topic: Create a TapToPhoneConfiguration Instance.
- Updated options for checking the device enrollment status in View the Device Enrollment Result.
- Added new SDK release and updated release version in code examples. See SDK Version 2.104.0 Release Notes.
25.07.02
- Added new SDK release and updated release version in code examples. See SDK Version 2.103.1 Release Notes.
25.07.01
- Added new topic: Customize Style Elements Using a UiConfiguration Instance.
- Updated instructions for choosing or entering the device serial number in Enabling Device Enrollment.
- Added new SDK release and updated release version in code examples. See SDK Version 2.103.0 Release Notes.
25.06.02
- Added new SDK release and updated release version in code examples. See SDK Version 2.102.0 Release Notes.
25.06.01
- Updated device requirements in Compatibility Requirements for Android Devices.
- Added new topic: Payment Devices Supported by the Tap to Pay on Android Solution.
- Updated instructions and code examples in Update the AndroidManifest.xml File.
- Updated UI screenshots in Customizing the Default User Interface.
- Revised requirements for device enrollment in Enabling Device Enrollment.
- Added a new feature to process PCI MPoC-compliant transactions. See PCI MPoC Standard Compliance.
25.05.01
- Renamed the product fromTap to Phone Android SolutiontoTap to Pay on Android Solution.
- Removed telephony enablement requirement fromCompatibility Requirements for Android Devices.
- Removed deprecated "Preparing Your Application for Testing and Production" and "Adding Dependencies" from Getting Started with the Tap to Pay on Android Solution section.
- Updated signature capture configuration parameters in Create a UiConfiguration Instance.
- Added new SDK release and updated release version in code examples. See SDK Version 2.101.1 Release Notes.
25.04.01
- Updated code example in Enroll a Previously Enrolled Device.
- Added new SDK release and updated release version in code examples. See SDK Version 2.100.0 Release Notes.
25.03
- Updated thetoolBarLogostyle element description in Customizing the Default User Interface.
- Revised Enabling Device Enrollment:
- Removed Enabling Device Enrollment Using theenrollDeviceActivity and Enabling Device Enrollment Using thegetEnrollDeviceIntentMethod.
- Updated View the Device Enrollment Result.
- Added new SDK release and updated release version in code examples. See SDK Version 2.99.0 Release Notes.
25.02
- Updated the code example in Configure the Project settings.gradle File.
- Revised Kotlin and Android Gradle version requirements and updated the code example in Configure the Project build.gradle File.
- Updated and renamed Obtaining a Merchant ID and Secret Key from the Business Center to Generating a Secret Key for an Existing Merchant ID.
- Removed requirement to enter the International Mobile Equipment Identity (IMEI) number when enrolling a mobile device in Enabling Device Enrollment.
- Removed outdated information about the io.mpos storage location for value constants in View the Device Enrollment Result.
- Added new SDK release and updated release version in code examples. See SDK Version 2.98.0 Release Notes.
25.01
- Added new SDK release and updated release version in code examples. See SDK Version 2.97.0 Release Notes.
24.13
- Updated supported Google services in Compatibility Requirements for Android Devices.
- Revised Summary Screen configuration details in Create a UiConfiguration Instance.
- Updated the location of constants for given values in View the Device Enrollment Result.
- Added new SDK release and updated release version in code examples. See SDK Version 2.96.0 Release Notes.
- Removed General Information release note about deprecation ofMposUi.Createfunction in SDK Version 2.95.0 Release Notes.
VISA Platform Connect: Specifications and Conditions for
Resellers/Partners
The following are specifications and conditions that apply to a Reseller/Partner enabling
its merchants through
Cybersource for
. Failure to meet any of the specifications and conditions below is
subject to the liability provisions and indemnification obligations under
Reseller/Partner’s contract with Visa/Cybersource.Visa Platform Connect
(“VPC”)
processing- Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer.
- Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer.
- Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer.
- Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR
OMISSIONS BY THE
Visa Platform Connect
ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA
NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR
ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE
RELEVANT Visa Platform Connect
ACQUIRER. Introduction to Acceptance Devices | Tap to Pay on Android Solution
Using existing mobile technology, the Acceptance Devices | Tap to Pay on Android Solution
enables any compatible Android smartphone to operate as a secure payment acceptance
device. By integrating the Tap to Pay on Android software development kit (SDK) into
your Android point-of-sale (POS) application, you can efficiently manage the payment
flow and deliver a seamless transaction experience for both merchants and customers.
For information about the current version of the SDK, see the Release Notes for Tap to Pay on Android Solution.
Compatibility Requirements for Android Devices
To accept contactless payments, your Android device must be compatible with the Tap to
Pay on Android Solution. These are the key requirements for a compatible Android
device:
- Tap to Pay Ready app is installed. You can download the app from the Google Play Store.
- Supports Google Mobile Services (GMS) and Google Play Store.
- Hardware-backed keystore.
- Near-field communication (NFC) enabled chip.
- Android 12 or later operating system. Android versions that do not receive security patches are not supported.
- Automatic time and date detection are enabled.
- Developer options are disabled.
- Device is not rooted. This setting prevents you from changing system-level files or settings.
Payment Devices Supported by the Tap to Pay on Android Solution
The Tap to Pay on Android Solution supports validated payment devices that meet
compatibility requirements. For more information, see Compatibility Requirements for Android Devices.
All supported models are not included in the table. If your device is not listed, contact
your implementation manager for help with determining if the device is supported.
Handheld Devices | Kiosk Devices | Tablet Devices |
|---|---|---|
Android compatible phones | Elo Touch 22-inch | iMin Falcon 2 |
Elo Touch M51 | oona 22 | MobiWire WM26 MobiTab |
iMin Swift 2 | Sunmi FLEX 3 | oona 10 |
MobiWire MobiGo2+ Pro | Orderman HT10 | |
MobiWire MP5 MobiPrint 5 | Sunmi CPad | |
MobiWire WM19 MobiTap | Sunmi D3 MINI | |
Orderman 10 | Sunmi V3 MIX | |
Sunmi L3 | ||
Sunmi M3 | ||
Sunmi V3 | ||
Zebra EM45 |
Transaction Workflow for the Tap to Pay on Android Solution
This diagram shows the transaction workflow for the Tap to Pay on Android
Solution.
Figure:
Tap to Pay on Android Solution Transaction Workflow
- The Android point-of-sale (POS) app integrates to the Tap to Pay on Android SDK.
- The merchant's Android POS app sends a request to the Tap to Pay on Android SDK to process a payment.
- The Tap to Pay on Android SDK user interface (UI) opens on the Android device screen and guides the customer through the payment flow.
- The Tap to Pay on Android SDK sends a response with the transaction result and details to the Android POS app.
PCI MPoC Standard Compliance
The Tap to Pay on Android Solution complies with the PCI Security Standards Council (PCI
SSC) Mobile Payments on COTS (MPoC) standard. This standard is typically referred to as
PCI MPoC
. Compliance with this standard helps ensure secure and reliable
payment processing across supported Android devices. The PCI-Certified MPoC Solution uses the Tap to Pay Ready app by Visa to meet PCI MPoC
software, attestation, and monitoring requirements. The app uses a transparent overlay
during payment processing to preserve the seamless UI experience. For app installation
instructions, see Install the Tap to Pay Ready App.
Using an app-to-app approach, payment processing is handled independently from your
point-of-sale (POS) application. Transactions are started in your POS app, securely
passed to the Tap to Pay Ready app for processing, and then returned to the original
app. This approach meets compliance requirements and helps you achieve these
benefits:
- Reduces PCI compliance complexity
- Lowers development and maintenance costs
- Accelerates time-to-market
- Enables seamless MPoC-related updates without affecting your app
For information about the PCI compliance status of the Tap to Pay on Android Solution,
see the PCI MPoC Solution Listing.
Transaction Workflow for the PCI-Certified MPoC Solution
This diagram shows the transaction workflow for the PCI-Certified MPoC Solution in the
Tap to Pay on Android Solution.
Figure:
PCI-Certified MPoC Solution Workflow
The PCI-Certified MPoC Solution workflow typically includes this sequence of events:
- The point-of-sale (POS) app sends a request to the Tap to Pay Ready app to initiate a secure switch to the other app. This activity is invisible to the customer, which ensures that the UI experience is seamless.
- The PCI-Certified MPoC Solution uses the Tap to Pay Ready app to provide a transparent overlay to securely capture payment details.
- The Tap to Pay Ready backend receives payment details from the Tap to Pay Ready app to complete transaction processing.
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
settings.gradle
FileFollow this step to configure your project's
settings.gradle
file.- Add the repository to your project'ssettings.gradlefile.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
build.gradle
FileFollow this step to configure your project's
build.gradle
file.- 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
build.gradle
FileFollow these steps to configure your module
build.gradle
file.- In the Android section, add these exclusion rules to your module'sbuild.gradlefile.android { ... packaging { resources { excludes.add("META-INF/*") excludes.add("LICENSE.txt") excludes.add("asm-license.txt") } } }
- 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" } }
- The Tap to Pay on Android Solution library publishes a release build type only. The debug build type is not available, so set thematchingFallbacksfield value torelease.android { ... buildTypes { ... debug { matchingFallbacks.apply { clear() add("release") } } } }
- IMPORTANTStay 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'sbuild.gradlefile.dependencies { ... // This is the Default UI dependency implementation("io.payworks:paybutton-android:2.107.0") // This is the Tap to Pay dependency implementation("io.payworks:mpos.android.taptophone:2.107.0") }
Update the AndroidManifest.xml File
AndroidManifest.xml
FileTo support a large heap size and ensure the necessary permissions for the Default
UI, update your Follow these steps to 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.AndroidManifest.xml
file:- Set theandroid:allowBackupattribute tofalseand theandroid:largeHeapattribute totrue.<application ... android:allowBackup="false" android:largeHeap="true" > ... </application>
- 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.
- To enable obfuscation for any of your build types, define the setting in the relevantbuild.gradlefile for your app.buildTypes { release { isMinifyEnabled = true proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro") } }
- If you are using ProGuard as an obfuscation tool in your app, add these rules to theproguard-rules.profile.# 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
:- In theBusiness Center, go to the left navigation panel and choosePayment Configuration>Key Management. The Key Management page appears.
- From the Merchant drop-down list, choose the merchant ID for which you want to generate a secret key.
- ClickGenerate Key.
- In the Recommended Key Types list, scroll down and chooseAcceptance Devices Secret Key.
- ClickGenerate Key. The Key Generation page appears.
- ClickGenerate Key. Your MID and secret key appear on the page.
- Click theCopyorDownloadicon to obtain the MID and secret key.
ADDITIONAL INFORMATION
IMPORTANTIf you choose to copy the secret key information instead of downloading it, be sure to save it locally. After you leave theBusiness CenterKey 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-posProduction:
POST
https://api.cybersource.com
/kms/v2/keys-sym-posRequired 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
mposUI
InstanceBefore 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.- Create anmposUIinstance using thecreatefunction.
- Set themerchantIdfield value to the merchant ID that you obtained.
- Set themerchantSecretfield value to the secret key that you obtained.
- Specify the environment by setting theproviderModefield value toTESTor toLIVE.
- Use theProviderMode.TESTsetting to test your integration without charging a real payment card. Use the merchant ID and secret key you obtained from the test environment.
- Use theProviderMode.LIVEsetting 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
UiConfiguration
InstanceUse 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).
- Re-try a failed transaction (RETRY_TRANSACTION).
- View all pre-authorizations after an incremental authorization (SHOW_TOTAL_PREAUTHORIZED).
- 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:- Create and configure theUiConfigurationinstance.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.SHOW_TOTAL_PREAUTHORIZED ) // 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
TapToPhoneConfiguration
InstanceCreate 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:- 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

Figure:
Tap to Pay on Android Default UI Style Elements

Figure:
Tap to Pay on Android Default UI Style Elements

- animationStrokeColor
- Stroke or outline color for animations.
- approvedStateColor
- Indicator color that appears for the approved transaction badge and animation.
- cardPresentAnimationStrokeColor
- Overrides theanimationStrokeColorstyle element in the card reader drawing on present-card animations. By default, this element is the same color as theanimationStrokeColorstyle 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 withPoor connectionandLow batterynotifications. 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 to0dpfor square corners,4dpfor slightly square corners (default), or32dpfor round corners.
- toolBarLogo
- A drawable image used for the merchant's company logo. The logo appears during the transaction.
Customize Style Elements Using a Theme
Follow these steps to customize the Default UI style elements.
- Introduce a new theme to your application that includes theTheme.PayButton2theme 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>
- Call one of these methods to set the theme:mposUi.themeRes = R.style.Theme_AppTheme_SampleTheme
Customize Style Elements Using a UiConfiguration Instance
UiConfiguration
InstanceUse 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
UiConfiguration
instance:- Create theUiConfigurationinstance.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:
- 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.- Use theenrollDeviceactivity 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
Theenrollactivity 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.- Use thereEnrollDeviceactivity 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
Theenrollactivity returns the resultIntent.
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()
Tap to Pay on Android Payment Services
Use the information in this section to process Tap to Pay on Android Solution payment
services.
Sale
Use the information in this section to process a sale. This type of transaction combines an
authorization and a capture into a single transaction.
Follow these steps to process a sale.
- Create aTransactionParametersobject and provide the required information for the payment.
- Retrieve thetransactionIntentvalue from themposUIobject, and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .charge(BigDecimal("1.00"), Currency.EUR) .customIdentifier("yourReferenceForTheTransaction") .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is completed and the Summary screen is dismissed, theonActivityResultmethod is triggered. This action returns information about the previous transaction.override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRANSACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved!\nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), "Transaction was declined, aborted, or failed", Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionfrom themposUIobject.val transactionObject = mposUi.latestTransaction
Refund
Use the information in this section to process a refund by referencing the original
transaction. You can issue refunds for either the full amount or a partial amount of
the original transaction. Stand-alone credits are also supported and can be
processed independently of a prior transaction. For more information, see Stand-Alone Credit.
Follow these steps to process a refund.
- Create aTransactionParametersobject and provide the required information for the payment.
- Retrieve thetransactionIntentvalue from themposUIobject and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .refund(“transactionIdentifier”) //Specify amount and currency for partial refunds //.amountAndCurrency(BigDecimal(1.00), Currency.EUR) .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is completed and the Summary screen is dismissed,onActivityResultis triggered. This action returns information about the previous transaction.override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRAN SACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved! \nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), "Transaction was decline d, aborted, or failed", Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionfrom themposUIobject.val transactionObject = mposUi.latestTransaction
Stand-Alone Credit
Use the information in this section to process a stand-alone credit. This type of
transaction enables you to issue a credit without referencing a previous
transaction. To complete the credit, the customer must present their payment card at
the time of processing.
WARNING
When processing a stand-alone credit, there is no limit on the
credit amount because the transaction does not reference the original purchase. To
help manage risk, it is recommended to use a refund transaction whenever possible.
For more information, see Refund.
Follow these steps to process a stand-alone credit.
- Create aTransactionParametersobject and provide the required information for the payment.
- Retrieve thetransactionIntentvalue from themposUIobject and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .refund(BigDecimal("1.00"), Currency.EUR) .customIdentifier("yourReferenceForTheTransaction") .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is completed and the Summary screen is dismissed,onActivityResultis triggered. This action returns information about the previous transaction.override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRANSACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved!\nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), "Transaction was declined, aborted, or failed", Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionfrom themposUIobject.val transactionObject = mposUi.latestTransaction
Check Transaction Status
Use the information in this section to request a check transaction status. This transaction type
is used to retrieve response data for a transaction that was lost or timed out. You
can initiate a status check when you have the
transactionIdentifier
value for the transaction that you want to query. When the check transaction status
request is completed, the transaction details are shown on the Summary screen.Follow these steps to request a check transaction status.
- Obtain thetransactionIdentifiervalue in theonActivityResultmethod of the original transaction.
- Retrieve the transactionsummaryIntentvalue from themposUIobject.
- Use thestartActivitymethod to initiate the Summary screen.val summaryIntent = mposUi.createTransactionSummaryIntent(transactionIdentifier = "transactionIdentifier") startActivityForResult(summaryIntent, MposUi.REQUEST_CODE_SHOW_SUMMARY)
- After the Summary screen is dismissed, theonActivityResultmethod is triggered. This action returns information about the previous transaction.override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) // Result code from closing the summary screen if (resultCode == MposUi.RESULT_CODE_SUMMARY_CLOSED) { // Accessing status from the transaction that was just queried val transactionStatus = mposUi.latestTransaction?.status Toast.makeText(activity, "Summary closed. Transaction status: $transactionStatus", Toast.LENGTH_SHORT).show() } }
- You can get the full transaction object by retrieving thelatestTransactionfrom the mposUi object.val transactionObject = mposUi.latestTransaction
Pre-Authorization
Use the information in this section to process a pre-authorization for an initial amount. A
pre-authorization transaction places a temporary hold on the customer's payment
card. The transaction amount can be captured at a later time.
Most authorizations expire within 5 to 7 days, as determined by the issuing bank.
When an authorization expires, your bank, the issuing bank, or payment processor
might require you to resubmit the authorization request and include a capture
request in the same message. For more information, seeCapture.
To help ensure successful transaction processing, it is recommended to monitor
authorization timelines and use combined authorization and capture requests when
necessary.
Follow these steps to process a pre-authorization.
- Create aTransactionParametersobject and provide the required information for the payment.
- Retrieve thetransactionIntentvalue from themposUIobject and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .charge(BigDecimal("1.00"), Currency.EUR) .customIdentifier("yourReferenceForTheTransaction") .autoCapture(false) .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is completed and the Summary screen is dismissed,onActivityResultis triggered. This action returns information about the previous transaction.Override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRANSACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved!\nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), "Transaction was declined, aborted, or failed", Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionfrom themposUIobject.val transactionObject = mposUi.latestTransaction
Incremental Authorization
Use the information in this section to process an incremental authorization. This type of
transaction can be made on a pre-authorization request to increase the authorized
amount before it is captured.
Follow these steps to process an incremental authorization.
- Create aTransactionParametersobject and provide the required information for the payment.
- Retrieve thetransactionIntentvalue from themposUIobject and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .incrementalAuthorization("transactionIdentifier") .amountAndCurrency(BigDecimal("1.00"), Currency.EUR) .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is completed and the Summary screen is dismissed,onActivityResultmethod is triggered. This action returns information about the previous transaction.Override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRAN SACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved!\nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), "Transaction was declined, aborted, or failed", Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionvalue from themposUIobject.val transactionObject = mposUi.latestTransaction
Capture
Use the information in this section to capture a pre-authorized transaction. The capture
request references the approved pre-authorization request.
Follow these steps to process a capture.
- Create aTransactionParametersobject and provide the required information for the payment.
- Retrieve thetransactionIntentvalue from themposUIobject and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .capture("transactionIdentifier") // Specify amount and currency for partial captures // .amountAndCurrency(BigDecimal("1.00"), Currency.EUR) .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is completed and the Summary screen is dismissed,onActivityResultmethod is triggered. This action returns information about the previous transaction.Override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRAN SACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved!\nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), "Transaction was declined, aborted, or failed", Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionvalue from themposUIobject.val transactionObject = mposUi.latestTransaction
Sale with On-Reader Tipping
Use the information in this section to process a sale with on-reader tipping. At the
start of each transaction, the terminal prompts the customer to add a tip by showing
suggested tip amounts. The customer chooses or enters a tip amount on the terminal
before presenting their payment card.
Follow these steps to process a sale with on-reader tipping.
- Create aTransactionParametersobject and provide the required information for the payment.
- Create aTippingProcessStepParametersobject to configure the tipping function. The options are percentage choice, tip amount, or total amount.
- Create aTransactionProcessParametersobject to add the tipping step.
- Retrieve thetransactionIntentvalue from themposUIobject, and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .charge(BigDecimal("1.00"), Currency.EUR) .customIdentifier("yourReferenceForTheTransaction") .build() // Use to display three tipping percentage choices val tipStep = TippingProcessStepParameters.Builder() .askForPercentageChoice() // Optional to configure tipping percentages | Default values = 10, 15, 20 // .percentages(BigDecimal("10"), BigDecimal("20"), BigDecimal("30")) // Optional to show confirmation screen // .showTotalAmountConfirmationScreen(true) .build() // Use to ask for tip amount // val tipStep = TippingProcessStepParameters.Builder() // .askForTipAmount() // Optional to show confirmation screen // .showTotalAmountConfirmationScreen(true) // .build() // Use to ask for total transaction amount including tip // val tipStep = TippingProcessStepParameters.Builder() // .askForTotalAmount() // Optional to show confirmation screen // .showTotalAmountConfirmationScreen(true) // .build() val processParameters = TransactionProcessParameters.Builder() .addStep(tipStep) .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters, processParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is completed and the Summary screen is dismissed,onActivityResultmethod is triggered. This action returns information about the previous transaction.Override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRANSACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved!\nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), “Transaction was declined, aborted, or failed”, Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionfrom themposUIobject.val transactionObject = mposUi.latestTransaction
Sale with Installment Details
Use the information in this section to process a sale with installment details. This type of
transaction can be used to include required installment payment details as part of
the transaction.
This transaction is available only in the Latin American & Caribbean (LAC)
region.
Follow these steps to process a sale with installment details.
- Create anInstallmentDetailsobject and set one ore more of the installment fields.// Set value of the builder to the number of installments val installmentDetails = InstallmentDetailsBuilder(5) // Set to PlanType.ISSUER_FUNDED for issuer funded plans .planType(PlanType.MERCHANT_FUNDED) .includesInterest(true) .governmentPlan(true) .build()
- Create aTransactionParametersobject and provide the required information for the payment.
- Retrieve thetransactionIntentfrom themposUiobject and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .charge(BigDecimal("1.00"), Currency.EUR) .customIdentifier("yourReferenceForTheTransaction") .installmentDetails(installmentDetails) .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is complete and the Summary screen is dismissed, theonActivityResultis triggered. This action returns information about the last transaction.override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRANSACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved!\nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), "Transaction was declined, aborted, or failed", Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionfrom themposUiobject.val transactionObject = mposUi.latestTransaction
Sale with Payment Facilitator Details
Use the information in this section to process a sale with payment facilitator details. This
type of transaction can be used to include required payment facilitator details as
part of the transaction.
Follow these steps to process a sale with payment facilitator details.
- Create aMerchantDetailsobject and set one ore more of the payment facilitator fields.val merchantDetails = MerchantDetailsBuilder() .salesOrganizationId("12345") .subMerchantId("SM67890") .merchantDescriptor("ExampleMerchant") .build()
- Create aTransactionParametersobject and provide the required information for the payment.
- Retrieve thetransactionIntentfrom themposUiobject and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .charge(BigDecimal("1.00"), Currency.EUR) .customIdentifier("yourReferenceForTheTransaction") .merchantDetails(merchantDetails) .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is complete and the Summary screen is dismissed, theonActivityResultis triggered. This action returns information about the last transaction.override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRANSACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved!\nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), "Transaction was declined, aborted, or failed", Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionfrom themposUiobject.val transactionObject = mposUi.latestTransaction
Sale with Tax Details
Use the information in this section to process a sale with tax details. This type of
transaction can be used to include required tax details as part of the
transaction.
Follow these steps to process a sale with tax details.
- Create aTaxDetailsobject and set one ore more of the tax fields.val taxDetails = TaxDetailsBuilder() .merchantTaxId("TaxID1234") .salesSlipNumber(12345678) .includedTaxAmount(BigDecimal("5.00")) .includedLocalTaxAmount(BigDecimal("1.00")) .includedNationalTaxAmount(BigDecimal("2.00")) .build()
- Create aTransactionParametersobject and provide the required information for the payment.
- Retrieve thetransactionIntentfrom themposUiobject and use thestartActivitymethod to initiate the transaction flow.val transactionParameters = TransactionParameters.Builder() .charge(BigDecimal("1.00"), Currency.EUR) .customIdentifier("yourReferenceForTheTransaction") .taxDetails(taxDetails) .build() val transactionIntent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(transactionIntent, MposUi.REQUEST_CODE_PAYMENT)
- After the transaction is complete and the Summary screen is dismissed, theonActivityResultis triggered. This action returns information about the last transaction.override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { when (resultCode) { // Result code from a successful transaction MposUi.RESULT_CODE_APPROVED -> { val transactionIdentifier = data?.getStringExtra(MposUi.RESULT_EXTRA_TRANSACTION_IDENTIFIER) Toast.makeText(findViewById(android.R.id.content),"Transaction approved!\nIdentifier: $transactionIdentifier", Toast.LENGTH_LONG).show() } // Result code from a declined, aborted or failed transaction MposUi.RESULT_CODE_FAILED -> { Toast.makeText(findViewById(android.R.id.content), "Transaction was declined, aborted, or failed", Toast.LENGTH_LONG).show() } } } }
- You can get the full transaction object by retrieving thelatestTransactionfrom themposUiobject.val transactionObject = mposUi.latestTransaction
Email a Customer Receipt
Follow these steps to email a customer receipt from a previous transaction.
- Retrieve theSendEmailReceiptIntentvalue from themposUIobject and use thestartActivitymethod to initiate the emailing a receipt flow.val SendEmailReceiptIntent = mposUi.createSendEmailReceiptIntent(transactionIdentifier) startActivityForResult(SendEmailReceiptIntent, MposUi.REQUEST_CODE_SEND_EMAIL)
- After the emailing activity is completed, theonActivityResultmethod is triggered. This action returns information about the previous transaction.override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) "onActivityResult: $resultCode".logDebug(TAG) val parentLayout: View = activity!!.findViewById(android.R.id.content) if (requestCode == MposUi.REQUEST_CODE_SEND_EMAIL) { if (resultCode == MposUi.RESULT_CODE_EMAIL_SUCCESS) { Snackbar.make(parentLayout, "Receipt sent via email", Snackbar.LENGTH_SHORT).show() } else if (resultCode == MposUi.RESULT_CODE_EMAIL_FAILED) { Snackbar.make(parentLayout, "Fail while sending receipt via email", Snackbar.LENGTH_SHORT).show() } } }
Release Notes for Tap to Pay on Android Solution
These release notes are organized by release name and version, from newest to oldest.
Each release note includes these details:
- Name of release
- Type of release: app or SDK
- Version number
- Operating system: Android or iOS
- Release date: MM-DD-YYYY format
- General information
- Improvements
- New features
- Fixed issues
- Updated requirements
- Security updates
- Hot fixes
SDK Version 2.107.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Pay on Android SDKs, version
2.107.0 for Android. The release date is 11-19-2025.
New Features
Tap to Pay: Added support for Discover and Diners payment cards.
Improvements
Improved the logic for displaying the Summary screen features.
Fixed Issues
- Fixed the issue that occasionally caused stand-alone credit transactions to stall.
- Fixed the issue that caused the SDK to crash when providing tax, installments, or payment facilitator details.
- PAX: Fixed the issue that caused the Retry button to not work after a failed receipt print for a completed transaction.
- Tap to Pay: Fixed the issue that caused the Tap icon to not appear on the Present Card screen.
- Tap to Pay: Fixed the issue that occasionally caused the touch area to not align correctly with the Cancel button.
General Information
- Deprecated PayButton 1.0 from the SDK. It will be removed from the next release.
- Removed thedefaultSummaryFeatureconfiguration option from the Summary screen parameters.
SDK Version 2.106.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Pay on Android SDKs, version
2.106.0 for Android. The release date is 10-09-2025.
New Features
- PAX: Added the ability to process Electronic Benefit Transfer (EBT) payment card transactions.
- PAX: Added the ability to read non-PCI custom magstripe cards such as gift cards and loyalty program cards.
SDK Version 2.105.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Pay on Android SDKs, version
2.105.0 for Android. The release date is 09-15-2025.
Improvements
Tap to Pay: Added the ability to configure the enrollment process to show or hide the serial number confirmation screen after a successful enrollment.
Fixed Issues
- Fixed the issue that caused the SDK to occasionally crash while using the tipping feature in some languages.
- Fixed the issue that caused automatic printing to occasionally fail when performing a refund.
SDK Version 2.104.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Pay on Android SDKs, version
2.104.0 for Android. The release date is 08-18-2025.
Improvements
- Improved the user experience on some screens by removing the requirement for user interaction.
- Improved the error messages that can appear during transactions.
- Tap to Pay Phone: Added the ability to configure the enrollment process to show a list of previously enrolled devices or to enable the merchant to enter the device serial number manually.
Archive of Release Notes
This archive of release notes for the PAX All-in-One Android Solution and Tap to Pay on
Android Solution is organized by release name and version, from newest to oldest. For
information about current releases, see . Also see, .
Each release note includes these details:
- Name of release
- Type of release: app or SDK
- Version number
- Operating system: Android or iOS
- Release date: MM-DD-YYYY format
These are the types of release notes published:
- General information
- Improvements
- New features
- Fixed issues
- Updated requirements
- Security updates
- Hot fixes
SDK Version 2.103.1 Release Notes
These release notes are for the PAX All-in-One and Tap to Pay on Android SDKs, version
2.103.1 for Android. The release date is 07-24-2025.
Fixed Issues
Fixed the issue that caused a blank screen to occasionally appear on the device after a
transaction processes.
SDK Version 2.103.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Pay on Android SDKs, version
2.103.0 for Android. The release date is 07-16-2025.
New Features
- Tap to Pay: Added a Device Selection screen that enables merchants to enroll a previously enrolled device without manually entering the serial number. This is now the default process when performing a device enrollment.
- Added the ability to customize the DefaultUI style elements using aUiConfigurationinstance.
Improvements
Tap to Pay: Re-enrolling a device can now be done without clearing the app data.
Fixed Issues
Applied general fixes to UI.
SDK Version 2.102.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Pay on Android SDKs, version
2.102.0 for Android. The release date is 06-27-2025.
New Features
- Tap to Pay: The solution is now PCI-MPoC compliant, which requires the Tap to Pay Ready app to be installed on the Android devices. After upgrading to this SDK version, re-enroll devices.
- Tap to Pay: Added support for American Express.
Improvements
- ThetoolBarlogostyle element now appears on the Present Card screen.
- The customer is no longer prompted for the tip amount a second time when a failed transaction is retried. Whatever tip amount the customer chose during the original transaction is included in the transaction.
- Tap to Pay: Improved the error messages that can appear during device enrollment and transaction processing.
SDK Version 2.101.1 Release Notes
These release notes are for the PAX All-in-One and Tap to Pay on Android SDKs, version
2.101.1 for Android. The release date is 05-23-2025.
New Features
- Added support for landscape mode on large-screen devices.
- Added support for the PAX A3700.
Improvements
- Improved the error message that can appear when a magnetic-stripe card is not read correctly by the device.
- Tap To Phone: Improved the error messages that can appear during enrollment of previously enrolled device.
Fixed Issues
- Fixed the issue that caused thetoolBarlogoelement not to work when using an XML file. This element controls the logo that appears on the device during transactions.
- Fixed the issue on the Signature screen that caused the transaction to fail when the Continue button was tapped multiple times.
SDK Version 2.100.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.100.0 for Android. The release date is 04-21-2025.
Improvements
Updated the UI to use Google Material Design 3.
Fixed Issues
Tap To Phone: Fixed the issue that caused the device serial number to not be shown after a failed device enrollment.
SDK Version 2.99.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.99.0 for Android. The release date is 03-25-2025.
New Features
Tap To Phone: Added the ability to re-enroll a previously enrolled device by providing the serial number to the SDK.
Improvements
- Improved the error message that appears when trying to start an unsupported transaction type.
- Tap To Phone: Improved the error messages that can appear during enrollment and transactions.
- Tap To Phone: The device serial number is now returned in theEnrollResultIntentafter performing a device enrollment.
SDK Version 2.98.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.98.0 for Android. The release date is 02-19-2025.
Updated Requirements
Tap to Phone: Added new ProGuard rule for Visa sensory branding. Include this rule in
your
proguard-rules.pro
file going forward.New Features
Added Arabic as a supported language.
Improvements
- Tap to Phone: Improved the device enrollment experience by removing the requirement to provide an International Mobile Equipment Identity (IMEI) number. After upgrading to this SDK version, devices need to be re-enrolled.
- Tap to Phone: Improved experience when attempting to perform a transaction with an unsupported card.
- Tap to Phone: Improved the error messages that can appear during enrollment and transactions.
- Tap to Phone: Added a check to confirm that NFC is enabled when a transaction is started.
Fixed Issues
- Fixed the issue that caused the print receipt buttons to not appear after requesting a check transaction status.
- Fixed the issue that required some dependencies to be imported manually.
SDK Version 2.97.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.97.0 for Android. The release date is 01-29-2025.
Improvements
- Tap to Phone: Improved the error messages that can appear during enrollment.
- Tap to Phone: Improved experience when attempting to perform a transaction with an unsupported currency.
- MOTO transactions will no longer prompt for tip if tipping is configured.
SDK Version 2.96.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.96.0 for Android. The release date is 11-26-2024.
Fixed Issues
Fixed various issues that occasionally caused the SDK to crash.
SDK Version 2.95.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.95.0 for Android. The release date is 10-22-2024.
Improvements
Tap to Phone: Improved the error messages that can appear during enrollment and
transactions.
Fixed Issues
- Fixed the issue that occasionally caused the "Low Battery" notification to be shown incorrectly.
- Fixed the issue that caused the value provided formerchantDescriptorto not be captured correctly.
SDK Version 2.94.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.94.0 for Android. The release date is 09-11-2024.
Fixed Issues
- Fixed the issue that rarely caused a crash when performing a magstripe transaction.
- Fixed the issue that rarely caused a crash during the card selection process.
New Features
- Added the ability to provide payment facilitator details when performing a transaction.
- Added the ability to provide tax details when performing a transaction.
- Added the ability to provide installment details for the Latin America & Caribbean (LAC) region when performing a transaction.
SDK Version 2.93.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.93.0 for Android. The release date is 08-19-2024.
Improvements
Improved the error messages that can appear for connection-related issues.
Updated Requirements
Updated the Mastercard sonic branding library to version 1.5.0. Use this version of the branding library with the SDK going forward.
Fixed Issues
- Fixed the issue that caused a crash ifMposUi.createwas called twice.
- Fixed the issue that caused receipt data to be missing when usingtransaction.getCustomerReceiptortransaction.getMerchantReceiptfunctions for Tap to Phone transactions.
- Fixed the issue that caused some devices to not have the expected behavior when the signature capture configuration was set toNONE.
- Fixed the issue that causedmposUi.latestTransactionobject to not be updated after requesting a check transaction status.
SDK Version 2.92.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.92.0 for Android. The release date is 07-05-2024.
Improvements
- Error message screens now have a timeout of 15 seconds.
- Improved the error message that appears when an offline transaction is attempted before the first online transaction is processed on the device.
SDK Version 2.91.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.91.0 for Android. The release date is 06-12-2024.
New Features
In order to skip signature capture, the signature capture configuration can be now be set to
NONE
.Improvements
Tap to Phone: Improved the error messages that can appear during device enrollment.
Fixed Issues
- Fixed the issue that caused the A920 MAX terminal not to be recognized correctly.
- Fixed the issue that caused the Retry button to appear on the Summary screen of approved transactions when theRETRY_TRANSACTIONfeature was configured as the default summary feature.
SDK Version 2.90.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.90.0 for Android. The release date is 05-16-2024.
New Features
- Added the ability to process partial refunds and captures from the transaction summary screen.
- Added support for PAX IM30 and PAX A920 MAX devices.
Improvements
Updated the Present Card animation that appears when processing an offline transaction.
Updated Requirements
- Tap to Phone: Updated the minimum supported operating system to Android 12.
- Updated the minimum supported Kotlin version to 1.8.
Fixed Issues
Fixed the issue that rarely caused the terminal to become unresponsive after attempting to use an unsupported card.
General Information
- Removed deprecatedstatementDescriptionandapplicationFeeparameters.
- Removed deprecated NightMode configuration.
SDK Version 2.89.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.89.0 for Android. The release date is 04-18-2024.
Fixed Issues
Fixed the issue that caused the merchant receipt for MOTO transactions not to include the
transaction status.
Improvements
Tap to Phone: Added translations for error messages in all supported languages.
SDK Version 2.88.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.88.0 for Android. The release date is 03-18-2024.
New Features
- PAX All-in-One SDK now supports:
- Offline transactions, also known asdeferred authorizationorstore and forward
- On-receipt tipping
- Added support for 67 additional currencies.
Improvements
Added the necessary ProGuard rules to the Tap to Phone SDK. This improvement eliminates
the need to maintain the rules in the app project.
SDK Version 2.87.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.87.0 for Android. The release date is 02-20-2024.
General Information
- NightMode was deprecated fromUiConfigurationand will be removed in the next release.
- Changed the "Bugfixes" release note title to "Fixed Issues."
Updated Requirements
Updated the Visa sensory branding library to version 2.2. Use this version of the
branding library with the SDK going forward.
Fixed Issues
- Fixed the issue that caused Default UI to crash if the app was running in the background during the card selection process.
- Fixed the issue that caused the incorrect formatting of the signature line on a printed receipt.
SDK Version 2.86.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.86.0. The release date is 01-16-2024.
Improvements
Improved error messages that appear during Tap to Phone device enrollment.
SDK Version 2.85.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.85.0. The release date is 12-19-2023.
Improvements
- Improved the UI experience when cancelling a Tap to Phone transaction from the PIN entry screen.
- Enabled the PAX device screen to power on automatically when a transaction is started when the screen is off.
Fixed Issues
- Fixed the issue related to integrators using WorkManager to schedule background work.
- Fixed the issue that occasionally caused the last screen of a canceled Tap to Phone transaction not to be dismissed automatically.
- Fixed the issue that caused MOTO transactions to crash if the language was set to German.
SDK Version 2.84.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.84.0. The release date is 11-23-2023.
Improvements
- Improved error handling at the start of a Tap to Phone transaction.
- Improved UI during initialization of a Tap to Phone transaction.
- Improved UX during cancellation of a Tap to Phone transaction.
SDK Version 2.83.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.83.0. The release date is 10-19-2023.
New Features
Tap to Phone now supports these transaction types: pre-authorization, incremental authorization, and capture.
Improvements
- Improved the display of error messages that are more than 40 characters long.
- Added an indicator on the Summary screen that the customer signature should be captured on the printed receipt for Tap to Phone transactions.
Fixed Issues
- Fixed the issue that resulted in an inconsistent state when a new transaction was started while the Summary screen was displayed.
- Fixed the issue that occurred during a successful refund transaction in which the Information screen showed the original transaction amount instead of the refunded amount.
- Fixed the issue that caused transactions that used currencies with two-digit numeric codes to fail.
SDK Version 2.82.0 Release Notes
These release notes are for the PAX All-in-One and Tap to Phone Android SDKs, version
2.82.0. The release date is 09-19-2023.
New Features
Tap to Phone now supports the on-device tipping feature.
Fixed Issues
- Fixed the issue that caused Tap to Phone transactions to freeze when using the signature on-receipt feature.
- Fixed the issue that caused the SDK to crash when attempting to recover a transaction after the Inconclusive screen is shown.
- Fixed the issue that caused the SDK to crash when starting a transaction with a zero amount and custom tipping.
- Fixed the issue that caused the wrong value to be returned when calling theisReadyForTransactionmethod before the first transaction.