On This Page
Getting Started with the PAX All-in-One Android Solution
Use the information in this section to get started with integrating the PAX All-in-One
Android Solution. After completing the integration, you can start processing payments.
For more information, see PAX All-in-One Payment Services.
Configuring the PAX All-in-One Android SDK
Use the information in this section to configure the PAX All-in-One 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 PAX All-in-One 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") } } } }
- 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 PAX libraries to the dependencies section of your module'sbuild.gradlefile.dependencies { ... // This is the Default UI dependency implementation("io.payworks:paybutton-android:2.110.0") // This is the PAX dependency implementation("io.payworks:mpos.android.accessories.pax:2.110.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
AndroidManifest.xml
file. Enabling a larger heap is essential
for scenarios where terminal updates require the handling and transfer of large
volumes of data.Follow these steps to update your
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 and PAX.<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"/> <!-- Needed for PAX integrations ! --> <uses-permission android:name="com.pax.permission.ICC"/> <uses-permission android:name="com.pax.permission.PICC"/> <uses-permission android:name="com.pax.permission.MAGCARD"/> <uses-permission android:name="com.pax.permission.PED"/> ... </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.# Jackson -keep class com.fasterxml.** { *; } -dontwarn com.fasterxml.** # Bolts -keep class bolts.** { *; } -dontwarn bolts.** # Couchbase -keep class com.couchbase.** { *; } -dontwarn com.couchbase.** # OkHttp -keepattributes Signature -keepattributes *Annotation* -dontwarn com.squareup.okhttp.** -keep class com.squareup.okhttp.* { *; } -dontwarn okio.** # Otto -keepclassmembers class ** { @com.squareup.otto.Subscribe public *; @com.squareup.otto.Produce public *; } # Acceptance Devices -keep class io.mpos.** { *; } -dontwarn io.mpos.** #PAX -dontwarn com.pax.** -keep class com.pax.** { *; }
Generating a Secret Key for an Existing Merchant ID
Use the information in this section to generate a secret key for an existing merchant ID
(MID) in the
Business Center
or by using a REST API request. The secret key and
MID are required values that you must enter in the mposUi
instance that
you create. For more information, see Creating an mposUi Instance.Generate a Secret Key for an Existing Merchant ID in the Business Center
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
If 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 use a REST API request to generate a secret key for an existing merchant ID
(MID). Enter these values in the
mposUi
instance you create. 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
mposUi
InstanceUse the information in this section to create and configure an
mposUI
instance.Create an mposUI Instance
mposUI
InstanceUse an
mposUi
instance to access the functionality of the PAX
All-in-One Android SDK. To complete this procedure, you must generate a secret key for
an existing merchant ID. For more information, seeGenerating a Secret Key for an Existing Merchant ID.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
mposUI
Instance To use the
mposUi
instance with the PAX All-in-One Android SDK, you must
configure the mposUi
instance by next creating a
UiConfiguration
instance.Create a UiConfiguration Instance
UiConfiguration
InstanceUse the
UiConfiguration
instance to configure the UI functionality
of the PAX All-in-One Android SDK.You can configure these parameters in the
UiConfiguration
instance that you create:- Configure the accessory as PAX.
- Configure these Summary screen features:
- Refund a transaction (REFUND_TRANSACTION).
- Send a receipt by email (SEND_RECEIPT_VIA_EMAIL).
- Capture a transaction (CAPTURE_TRANSACTION).
- Print a customer receipt (PRINT_CUSTOMER_RECEIPT).
- Print a merchant receipt (PRINT_MERCHANT_RECEIPT).
- Retry a failed transaction (RETRY_TRANSACTION).
- Increment a transaction (INCREMENT_TRANSACTION).
- Add a tip after a sale with on-receipt tipping(ADJUST_TIP).
- 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 display 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.
- Configure the merchant receipt (MERCHANT_RECEIPT) or customer receipt (CUSTOMER_RECEIPT) to be printed automatically.
- Configure the accessibility mode.
Follow this step to create and configure the
UiConfiguration
instance in your app:- Create theUiConfigurationinstance.mposUi.configuration = UiConfiguration( terminalParameters = AccessoryParameters.Builder(AccessoryFamily.PAX).integrated().build(), summaryFeatures = setOf( SummaryFeature.REFUND_TRANSACTION, SummaryFeature.SEND_RECEIPT_VIA_EMAIL, SummaryFeature.CAPTURE_TRANSACTION, SummaryFeature.PRINT_CUSTOMER_RECEIPT, SummaryFeature.PRINT_MERCHANT_RECEIPT, SummaryFeature.RETRY_TRANSACTION, SummaryFeature.INCREMENT_TRANSACTION SummaryFeature.ADJUST_TIP ) // 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, // Use this to enable automatic receipt printing // automaticPrintingOption = AutomaticPrintingOption.MERCHANT_RECEIPT, // Use this to enable accessibility mode // accessibilityModeOption = AccessibilityModeOption.OPTION_VISIBLE, )
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:
PAX All-in-One Default UI Style Elements

Figure:
PAX All-in-One Default UI Style Elements

Figure:
PAX All-in-One 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
- 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.
- 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> <!-- Stroke color for terminal in present card animation. By default the same as animationStrokeColor --> <item name="cardPresentAnimationStrokeColor">@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
InstanceThis customization feature enables you 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 device is in dark mode, the Default UI payment flow screens appear in darker
contrasting colors than the colors used with the default screen settings (light mode). The
Dark Mode feature might be used in low-light settings such as restaurants and bars. For
more information about this setting, see the Android documentation.
The default dark mode background color is dark gray (#121212). To change the background
color to pure black (#000000), add a new
Theme.PayButton2
theme in the
value-night
folder.Follow this step to change dark mode behavior.
- If you want to enforce light or dark mode across your application and Default UI, regardless of the phone's dark mode setting, use this Android method. This example enforces night mode.AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
Installing Your Application on Debug PAX Devices
Use the information in this section to install your application on a debug PAX device.
Debug devices ordered from
Cybersource
display the DEBUG only Not for
COMMERCIAL
watermark in the bottom-right corner of the device screen. This type
of device is required when you are developing your own application. Using a debug device
enables you to install Android package kits (APKs) and transfer files using a USB cable. Production (live) device screens do not display a watermark. For security reasons, you
cannot install an APK directly on a live device. The only way to update applications on
this type of device is by download from PAXSTORE. Also, only production devices can be
deployed in the market. For more information about production devices, see Making Your Application Available on Production PAX Devices.
Install an Android Application on Debug PAX Devices
PAX devices that are ordered from
Cybersource
to debug your application, display
the DEBUG only Not for COMMERCIAL
watermark on the bottom-right corner of the
device screen.Follow this step to install an Android application on a debug PAX device.
- Connect the PAX device to your computer using the USB cable provided with the device.
- Depending on your development tool or operating system, use one of these methods:
- If you are using Android Studio, you can install the Android Package Kit (APK) file directly on the PAX device.
- Alternatively, you can transfer the APK to the test device, by selecting the file on the device, and then following the instructions to install it.
- If you are using an Apple computer, you can use a file transfer tool, such as Android File Transfer, to copy the APK file to the PAX device. Choose the APK file on the device and follow the on-screen instructions to install the file.
- If you are using a Windows computer, you can copy the APK file to the PAX device. Choose the APK file on the device and follow the on-screen instructions to install the APK file.
Making Your Application Available on Production PAX Devices
Use the information in this section to make your app available for use on production
(live) PAX devices.
The difference between a production and debug PAX device is that a debug device ordered
from
Cybersource
has a DEBUG only Not for COMMERCIAL
watermark in
the bottom-right corner of the device screen. A production device does not have a
watermark. For more information about debug devices, see Installing Your Application on Debug PAX Devices.You must prepare and submit your app before it can be added to PAXSTORE, which is a PAX
Technology platform where you can publish your point-of-sale (POS) device apps.
Submit Your Android Application in the Business Center
Business Center
You must submit your app for review in the
Business Center
. The app submission is
reviewed and receives comment or approval. After approval, Cybersource
submits your Android Package Kit (APK) file to PAXSTORE for
publication. The published app can be downloaded and used on production PAX
devices.Before starting the app submission process, verify that your APK file is not larger than 200 MB.
Follow these steps to submit your Android application.
- In theBusiness Center, go to the left navigation panel and chooseAcceptance Devices > App Submission.
- Complete the form to provide required information about your Android application.
- ClickSubmit.