Migrating from PayButton to the Default UI

Use these instructions to migrate from the previous version of PayButton to the Default UI (formerly known as "PayButton 2.0"). 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:4.2.1" classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.31" } }
Setting Up the Module build.gradle
Add the Kotlin plugin.
plugins { ... id 'kotlin-android' }
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
dependencies { ... // This is the Default UI dependency implementation 'io.payworks:paybutton-android:2.65.0' // Add this dependency if you want to use Pax card reader implementation 'io.payworks:mpos.android.accessories.pax:2.65.0' // Add this dependency if you want to use Miura card reader implementation 'io.payworks:mpos.java.accessories.miura:2.65.0' // Add this dependency if you want to connect to the Miura via bluetooth implementation 'io.payworks:mpos.android.comlinks.bluetooth:2.65.0' // Add this dependency if you want to connect to the Miura via wifi implementation 'io.payworks:mpos.java.comlinks.tcp:2.65.0' }
Updating the AndroidManifest File
Make sure to update the necessary permissions in your
<!-- 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="android.permission.READ_EXTERNAL_STORAGE"/> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/> <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
method was used to create an instance of the
val mposUi = MposUi.initialize( context, ProviderMode.TEST, "MerchantIdentifier", "MerchantSecret" )
In the Default UI, instead of using the
method that was used to create an instance of the
object in the previous version of PayButton, use the
method to create an instance of the
val mposUi = MposUi.create( context, ProviderMode.TEST, "MerchantIdentifier", "MerchantSecret" )
MposUi mposUi = MposUi.create( this, 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
object, and individual methods were used to set the features on the
object. For example, the code shown below enables the Summary screen to display the
Print receipt
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
method. Instead, you create an
instance and use the
method. Examples are shown for connecting a PAX and Miura terminals. The Miura configuration uses the
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,
values are created in the same way that they were created for the previous version of PayButton. This procedure includes using the
method that was used previously.
val transactionParameters = TransactionParameters.Builder() .charge(BigDecimal("5.00"), Currency.EUR) .subject("Bouquet of Flowers") .customIdentifier("yourReferenceForTheTransaction") .build()
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
method as the previous version of PayButton. The
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.
val intent = mposUi.createTransactionIntent(transactionParameters) startActivityForResult(intent, MposUi.REQUEST_CODE_PAYMENT)
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
callback. If you need the full transaction object, call the
method to retrieve all the data about the last transaction.
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() } }
@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
parent theme and specify colors to match your brand's visual identity. For more information about customizing the UI, see Customization.
Related Links