Migrating from PayButton to Default UI

Use these instructions to migrate from the previous version of PayButton to the Default UI. Currently, the Default UI is available for PAX and Miura terminals only.
Setting Up the Project build.gradle
Add the Kotlin gradle plugin, which is required in order to use the Default UI.
buildscript {
        ...
        dependencies {
                classpath "com.android.tools.build:gradle:7.0.4"
                classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.21"
        }
}
Setting Up the Module build.gradle
The Default UI library publishes a release build type only, so you must add this:
android {
 
    ...
 
    buildTypes {
        ...
        debug {
            matchingFallbacks = ['release']
        }
    }
}
Add the 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.76.0'

    // Add this dependency if you want to use Pax card reader
    implementation 'io.payworks:mpos.android.accessories.pax:2.76.0'

    // Add this dependency if you want to use Miura card reader
    implementation 'io.payworks:mpos.java.accessories.miura:2.76.0'

    // Add this dependency if you want to connect to the Miura via bluetooth
    implementation 'io.payworks:mpos.android.comlinks.bluetooth:2.76.0'

    // Add this dependency if you want to connect to the Miura via wifi
    implementation 'io.payworks:mpos.java.comlinks.tcp:2.76.0'
}
Updating the AndroidManifest File
Make sure to update the necessary permissions in your
AndroidManifest.xml
 file.
<!-- 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 Miura integrations !-->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<!-- 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"/>
Initializing the MposUI Object
In the previous version of PayButton, this
initialize()
 method was used to create an instance of the
MposUI
 object.
val mposUi = MposUi.initialize( context, ProviderMode.TEST,
                    "MerchantIdentifier", "MerchantSecret" )
In the Default UI, instead of using the
initialize()
 method that was used to create an instance of the
MposUI
 object in the previous version of PayButton, use the
create()
 method to create an instance of the
MposUI
 object.
Kotlin
val mposUi = MposUi.create(
        ProviderMode.TEST,
        "MerchantIdentifier",
        "MerchantSecret"
    )
Java
MposUi mposUi = MposUi.create(
            ProviderMode.MOCK,
            "yourMerchantIdentifier",
            "yourMerchantSecret");
Setting Up the UI Configurations
The Default UI includes changes in the UI configurations such as payment options, Summary screen features, and signature capture.
In the previous version of PayButton, the
MposUi getConfiguration()
 method was used to retrieve the
UiConfiguration
 object, and individual methods were used to set the features on the
UiConfiguration
 object. For example, the code shown below enables the Summary screen to display the
Print receipt
 and
Send receipt via email
 features. For more information about customizable display features, see Summary Screen.
ui.getConfiguration().setSummaryFeatures(EnumSet.of(MposUiConfiguration.SummaryFeature.PRINT_RECEIPT, 
MposUiConfiguration.SummaryFeature.SEND_RECEIPT_VIA_EMAIL)
The Default UI does not use the
getConfiguration()
 method. Instead, you create an
UiConfiguration
 instance and use the
setConfiguration()
 method. Examples are shown for connecting a PAX and Miura terminals. The Miura configuration uses the
TransactionParameters.Builder()
.
Kotlin (PAX)
val configuration = UiConfiguration(
    paymentOptions = setOf(PaymentOption.CARD, PaymentOption.MOTO),
    signatureCapture = SignatureCapture.ON_SCREEN,
    resultDisplayBehavior = ResultDisplayBehavior.DISPLAY_INDEFINITELY,
    accessibilityModeOption = AccessibilityModeOption.OPTION_VISIBLE,
    summaryFeatures = setOf(
        SummaryFeature.CAPTURE_TRANSACTION,
        SummaryFeature.PRINT_CUSTOMER_RECEIPT,
        SummaryFeature.PRINT_MERCHANT_RECEIPT,
        SummaryFeature.REFUND_TRANSACTION,
        SummaryFeature.SEND_RECEIPT_VIA_EMAIL
    ),
    terminalParameters = AccessoryParameters.Builder(AccessoryFamily.PAX)
        .integrated()
        .build()
)
mposUi.configuration = configuration
Java (PAX)
UiConfiguration configuration = new UiConfiguration.Builder()
        .paymentOptions(
                EnumSet.of(
                        UiConfiguration.PaymentOption.CARD,
                        UiConfiguration.PaymentOption.MOTO
                )
        )
        .signatureCapture(UiConfiguration.SignatureCapture.ON_SCREEN)
        .resultDisplayBehavior(UiConfiguration.ResultDisplayBehavior.DISPLAY_INDEFINITELY)
        .accessibilityModeOption(UiConfiguration.AccessibilityModeOption.OPTION_VISIBLE)
        .summaryFeatures(
                EnumSet.of(
                        UiConfiguration.SummaryFeature.SEND_RECEIPT_VIA_EMAIL,
                        UiConfiguration.SummaryFeature.PRINT_CUSTOMER_RECEIPT,
                        UiConfiguration.SummaryFeature.PRINT_MERCHANT_RECEIPT,
                        UiConfiguration.SummaryFeature.REFUND_TRANSACTION,
                        UiConfiguration.SummaryFeature.CAPTURE_TRANSACTION
                )
        )
        .terminalParameters(
                new AccessoryParameters.Builder(AccessoryFamily.PAX)
                        .integrated()
                        .build()
        )
        .build();
mposUi.setConfiguration(configuration);
Kotlin (Miura)
AccessoryParameters.Builder(AccessoryFamily.MIURA_MPI)
    .bluetooth()
    .build()
Java (Miura)
new AccessoryParameters.Builder(AccessoryFamily.MIURA_MPI)
    .bluetooth()
    .build();
Creating Transaction Parameters
In the Default UI,
TransactionParameters
 values are created in the same way that they were created for the previous version of PayButton. This procedure includes using the
TransactionParameters.Builder()
 method that was used previously.
Kotlin
val transactionParameters = TransactionParameters.Builder()
            .charge(BigDecimal("5.00"), Currency.EUR)
            .subject("Bouquet of Flowers")
            .customIdentifier("yourReferenceForTheTransaction")
            .build()
Java
TransactionParameters transactionParameters = TransactionParameters.Builder()
            .charge(BigDecimal("5.00"), Currency.EUR)
            .subject("Bouquet of Flowers")
            .customIdentifier("yourReferenceForTheTransaction")
            .build()
Initiating a Transaction
The Default UI uses the same
createTransactionIntent()
 method as the previous version of PayButton. The
MposUi
 object was created according to the latest specification in the previous version of PayButton, so no change is required for creating the transaction intent in the Default UI.
Kotlin
val intent = mposUi.createTransactionIntent(transactionParameters)
startActivityForResult(intent, MposUi.REQUEST_CODE_PAYMENT)
Java
Intent intent = mposUi.createTransactionIntent(transactionParameters);
startActivityForResult(intent, MposUi.REQUEST_CODE_PAYMENT);
Retrieving the Transaction Result
The result of a transaction can be retrieved using the
onActivityResult
 callback. If you need the full transaction object, call the
getLatestTransaction()
 method to retrieve all the data about the last transaction.
Kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == MposUi.REQUEST_CODE_PAYMENT)
        if (resultCode == MposUi.RESULT_CODE_APPROVED) {
            val transactionIdentifier = data?.extras?.get(MposUi.RESULT_EXTRA_TRANSACTION_IDENTIFIER)
            val transactionObject = mposUi.latestTransaction
            Snackbar.make(findViewById(android.R.id.content), "Transaction approved\n$transactionIdentifier", Snackbar.LENGTH_SHORT).show()
        } else {
            Snackbar.make(findViewById(android.R.id.content), "Transaction was declined, aborted, or failed", Snackbar.LENGTH_SHORT).show()
        }
}
Java
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);

    if (requestCode == MposUi.REQUEST_CODE_PAYMENT) {
        if (resultCode == MposUi.RESULT_CODE_APPROVED) {
            // Transaction was approved
            String transactionIdentifier = data.getStringExtra(MposUi.RESULT_EXTRA_TRANSACTION_IDENTIFIER);
            Transaction transactionObject = mposUi.getLatestTransaction();
            Toast.makeText(this, "Transaction approved, identifier: " + transactionIdentifier, Toast.LENGTH_LONG).show();
        } else {
            // Card was declined, or transaction was aborted, or failed
            // (e.g. no internet or accessory not found)
            Toast.makeText(this, "Transaction was declined, aborted, or failed",
                    Toast.LENGTH_LONG).show();
        }
    }
}
Customizing the UI
The Default UI includes major upgrades to UI customization options. The previous version of PayButton included limited customization options. For example, you could control only the colors for these UI style elements:
  • setColorPrimary
    : The color of the icon and top action bar.
  • setColorPrimaryDark
    : The color of the status bar (affects Android L and later).
  • setTextColorPrimary
    : The color of the primary text.
In the Default UI, you can define your own style inherited from the
Theme.PayButton2
 parent theme and specify colors to match your brand's visual identity. For more information about customizing the UI, see Customization.
Related Links