FILTER BY TAG

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

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

Configure the Project
build.gradle
File

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

Configure the Module
build.gradle
File

Follow these steps to configure your module
build.gradle
file.
  1. In the Android section, add these exclusion rules to your module's
    build.gradle
    file.
    android {     ...     packaging {         resources {             excludes.add("META-INF/*")             excludes.add("LICENSE.txt")             excludes.add("asm-license.txt")         }     } }
  2. In order for the app to support Java 17 features, you must set the compatibility levels.
    android {     ...     compileOptions {         sourceCompatibility = JavaVersion.VERSION_17         targetCompatibility = JavaVersion.VERSION_17     }     kotlinOptions {         jvmTarget = "17"     } }
  3. The PAX All-in-One Android Solution library publishes a release build type only. The debug build type is not available, so set the
    matchingFallbacks
    field value to
    release
    .
    android {     ...     buildTypes {         ...         debug {             matchingFallbacks.apply {                 clear()                 add("release")             }         }     } }
  4. 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's
    build.gradle
    file.
    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

To support a large heap size and ensure the necessary permissions for the Default UI, update your
AndroidManifest.xml
file. Enabling a larger heap is essential for scenarios where terminal updates require the handling and transfer of large volumes of data.
Follow these steps to update your
AndroidManifest.xml
file.
  1. Set the
    android:allowBackup
    attribute to
    false
    and the
    android:largeHeap
    attribute to
    true
    .
    <application     ...     android:allowBackup="false"     android:largeHeap="true"     >     ... </application>
  2. Enable the needed permissions for the Default UI 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.
  1. To enable obfuscation for any of your build types, define the setting in the relevant
    build.gradle
    file for your app.
    buildTypes {     release {         isMinifyEnabled = true         proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")     } }
  2. If you are using ProGuard as an obfuscation tool in your app, add these rules to the
    proguard-rules.pro
    file.
    # 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

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

    ADDITIONAL INFORMATION

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

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

You can 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-pos
Production:
POST
https://api.cybersource.com
/kms/v2/keys-sym-pos

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

keyInformation.organizationId

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

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

Creating an
mposUi
Instance

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

Create an
mposUI
Instance

Use 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:
  1. Create an
    mposUi
    instance using the
    create
    function.
  2. Set the
    merchantId
    field value to the merchant ID that you obtained.
  3. Set the
    merchantSecret
    field value to the secret key that you obtained.
  4. Specify the environment by setting the
    providerMode
    field value to
    TEST
    or to
    LIVE
    • Use the
      ProviderMode.TEST
      setting to test your integration without charging a real payment card. Use the merchant ID and secret key you obtained from the test environment.
    • Use the
      ProviderMode.LIVE
      setting to process live transactions. Use the merchant ID and secret key you obtained from the production environment.
    val mposUi = MposUi.create(              providerMode = ProviderMode.LIVE, // ProviderMode.TEST              merchantId = "MerchantId",              merchantSecret = "SecretKey"          )

Configure an
mposUI
Instance

To use the
mposUi
instance with the PAX All-in-One Android SDK, you must configure the
mposUi
instance by next creating a
UiConfiguration
 instance.

Create a
UiConfiguration
Instance

Use 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:
  1. Create the
    UiConfiguration
     instance.
    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
Example 1, PAX All-in-One Default UI style elements showing icons, labeled buttons,
          colors, and text

Figure:

PAX All-in-One Default UI Style Elements
Example 2, PAX All-in-One Default UI style elements showing icons, labeled buttons,
          colors, and text

Figure:

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

Customize Style Elements Using a Theme

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

Customize Style Elements Using a
UiConfiguration
Instance

This 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
Follow this step to customize Default User Interface style elements using a
UiConfiguration
instance:
  1. Create the
    UiConfiguration
     instance.
    mposUi.configuration = UiConfiguration(       // other UiConfiguration parameters       toolbarLogo = "....",       colorScheme = UiConfiguration.ColorScheme(         colorPrimary = 0xFF1A1F71,         colorOnPrimary = 0xFFFFFFFF,         colorSurface = 0xFFFFFFFF,         colorOnSurface = 0xFF1C1B1B,       ),       cornerRadius = UiConfiguration.CornerRadius.ROUND     )

Enable Dark Mode in the Default User Interface

When the 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.
  1. 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.
  1. Connect the PAX device to your computer using the USB cable provided with the device.
  2. 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

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.
  1. In the
    Business Center
    , go to the left navigation panel and choose
    Acceptance Devices > App Submission
    .
  2. Complete the form to provide required information about your Android application.
  3. Click
    Submit
    .