Login

Contact

Integrate the PayButton

Install

The PayButton requires minSdkVersion 16 and compileSdkVersion 25.

  • Add our repository to your project's build.gradle:

allprojects {
    repositories {
        jcenter()
        maven {
            url "http://releases.payworks.io/artifactory/mpos"
        }
    }
}
                
            
  • Add the following exclusion rules to your module's build.gradle (inside the android section):

packagingOptions {
    exclude 'META-INF/DEPENDENCIES.txt'
    exclude 'META-INF/LICENSE.txt'
    exclude 'META-INF/NOTICE.txt'
    exclude 'META-INF/DEPENDENCIES'
    exclude 'META-INF/LICENSE'
    exclude 'META-INF/NOTICE'
    exclude 'LICENSE.txt'
}
                
            
  • Add the libraries to the dependencies section of your module's build.gradle:

dependencies {
    compile 'com.android.support:appcompat-v7:25.0.1'
    compile 'com.android.support:support-v4:25.0.1'
    compile 'com.android.support:cardview-v7:25.0.1'

    compile 'com.squareup:otto:1.3.5'
    compile 'com.squareup.okhttp:okhttp:2.7.4'
    compile 'com.squareup.okhttp:okhttp-ws:2.7.4'
    compile 'com.parse.bolts:bolts-android:1.2.1'
    compile 'com.fasterxml.jackson.core:jackson-databind:2.4.4'

    compile 'io.payworks:mpos.android.ui:2.18.1:@aar'
    compile 'io.payworks:mpos.android.core:2.18.1:@aar'

    // Add those three dependencies if you want to use a Miura card reader
    compile 'io.payworks:mpos.android.accessories.miura:2.18.1:@aar'
    compile 'io.payworks:mpos.android.comlinks.bluetooth:2.18.1:@aar'
    compile 'io.payworks:mpos.android.comlinks.tcp:2.18.1:@aar'
}
                
            

Peform a payment

This is how you start a payment in mock mode:


void paymentButtonClicked() {
    MposUi ui = MposUi.initialize(this, ProviderMode.MOCK,
            "merchantIdentifier", "merchantSecretKey");

    ui.getConfiguration().setSummaryFeatures(EnumSet.of(
            // Add this line, if you do want to offer printed receipts
            // MposUiConfiguration.SummaryFeature.PRINT_RECEIPT,
            MposUiConfiguration.SummaryFeature.SEND_RECEIPT_VIA_EMAIL)
    );

    // Start with a mocked card reader:
    AccessoryParameters accessoryParameters = new AccessoryParameters.Builder(AccessoryFamily.MOCK)
                                                            .mocked()
                                                            .build();
    ui.getConfiguration().setTerminalParameters(accessoryParameters);

    // Add this line if you would like to collect the customer signature on the receipt (as opposed to the digital signature)
    // ui.getConfiguration().setSignatureCapture(MposUiConfiguration.SignatureCapture.ON_RECEIPT);

    /* When using the Bluetooth Miura Shuttle / M007 / M010, use the following parameters:
    AccessoryParameters accessoryParameters = new AccessoryParameters.Builder(AccessoryFamily.MIURA_MPI)
                                                                     .bluetooth()
                                                                     .build();
    ui.getConfiguration().setTerminalParameters(accessoryParameters);
    */


    /* When using the WiFi Miura M010, use the following parameters:
    AccessoryParameters accessoryParameters = new AccessoryParameters.Builder(AccessoryFamily.MIURA_MPI)
                                                                     .tcp("192.168.254.123", 38521)
                                                                     .build();
    ui.getConfiguration().setTerminalParameters(accessoryParameters);
    */


    TransactionParameters transactionParameters = new TransactionParameters.Builder()
                                                            .charge(new BigDecimal("5.00"), io.mpos.transactions.Currency.EUR)
                                                            .subject("Bouquet of Flowers")
                                                            .customIdentifier("yourReferenceForTheTransaction")
                                                            .build();

    Intent intent = ui.createTransactionIntent(transactionParameters);
    startActivityForResult(intent, MposUi.REQUEST_CODE_PAYMENT);
}
                
            

The result is then delivered to your activity:


@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {

    if (requestCode == MposUi.REQUEST_CODE_PAYMENT) {
        if (resultCode == MposUi.RESULT_CODE_APPROVED) {
            // Transaction was approved
            Toast.makeText(this, "Transaction approved", 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();
        }
        // Grab the processed transaction in case you need it
        // (e.g. the transaction identifier for a refund).
        // Keep in mind that the returned transaction might be null
        // (e.g. if it could not be registered).
        Transaction transaction = MposUi.getInitializedInstance().getTransaction();
    }
}
                
            

More information on the completed transaction statuses and what they mean can be found here.

If you have problems with onActivityResult not being called, this might be caused by starting the PayButton Activity from the wrong Activity / Fragment. This Stackoverflow post might help you.

Load merchant data from your backend

Right now, you have hardcoded the merchantIdentifier and merchantSecretKey. This means that all payments would be routed to the same merchant. 

For a live solution, you might want to support multiple merchants, e.g. two different restaurants, to route the payment correctly. To support multiple merchants, store the following data on your backend:

  1. merchantIdentifier and  merchantSecretKey. They identify to which merchant the payment is routed.

  2. Whether the merchant is a TEST or LIVE merchant.

  3. The reader model the merchant uses.

​You can then fetch this data before a transaction and configure the PayButton correctly:


MposUi ui = MposUi.initialize(this,
    <ProviderMode.TEST or ProviderMode.LIVE, loaded from your backend>,
    <MerchantIdentifier loaded from your backend>, <MerchantSecretKey loaded from your backend>);
                
            

Customize the PayButton

UI customization: Change the colors

123

You can choose the following colors:

  1. setColorPrimary: The icon's and top action bar's color
  2. setColorPrimaryDark: The color of the status bar (affects Android L and later)
  3. setTextColorPrimary: The primary text color

ui.getConfiguration().getAppearance()
     .setColorPrimary(Color.parseColor("#9c27b0"))
     .setColorPrimaryDark(Color.parseColor("#7b1fa2"))
     .setTextColorPrimary(Color.WHITE);
                
            

Receipt customization

You are required to offer an email or printed payment receipt to the shopper. The PayButton therefore allows the merchant to send an email payment receipt right after a transaction.

You might want to prevent this behavior, e.g. if you send your own receipts already and just want to append the required payment data. You can disable the built-in email receipts by removing MposUiConfiguration.SummaryFeature.SEND_RECEIPT_VIA_EMAIL from the setSummaryFeatures EnumSet.

If you choose to remove this, you must implement another way for the merchant to send out a receipt. You can either programmatically send the same receipt that the PayButton would send, or send a custom or printed one. For custom and printed receipts, you are required to display specific data. See this page for details.