Integrate the SDK

To get started with your own implementation, add the SDK to your app first. Then, choose an activity of your App. This should be the activity that starts the payment.

Paste the following code into your activity. Replace MERCHANT_IDENTIFIER and  MERCHANT_SECRET_KEY with your testing credentials, or use TransactionProvider in mocked mode. Use the correct value of AccessoryParameters for your reader.

void transaction() {
    final TransactionProvider transactionProvider = Mpos.createTransactionProvider(this,
            ProviderMode.TEST,
            "MERCHANT_IDENTIFIER",
            "MERCHANT_SECRET_KEY");

    /* For starting transaction in mocked mode use fallowing provider:
    final TransactionProvider transactionProvider = Mpos.createTransactionProvider(this,
            ProviderMode.MOCK,
            "merchantIdentifier",
            "merchantSecretKey");
    */


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





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

    TransactionProcess paymentProcess = transactionProvider.startTransaction(transactionParameters, accessoryParameters,
            new TransactionProcessWithRegistrationListener() {

                @Override
                public void onRegistered(TransactionProcess process,
                                         Transaction transaction) {
                    Log.d("mpos", "transaction identifier is: " + transaction.getIdentifier() + ". Store it in your backend so that you can always query its status.");
                }

                @Override
                public void onStatusChanged(TransactionProcess process ,
                                            Transaction transaction,
                                            TransactionProcessDetails processDetails) {
                    Log.d("mpos", "status changed: " + Arrays.toString(processDetails.getInformation()));
                }

                @Override
                public void onCustomerSignatureRequired(TransactionProcess process,
                                                        Transaction transaction) {
                    // in a live app, this image comes from your signature screen
                    Bitmap.Config conf = Bitmap.Config.ARGB_8888;
                    Bitmap bm = Bitmap.createBitmap(1, 1, conf);
                    byte[] signature = AndroidImageHelper.byteArrayFromBitmap(bm);
                    process.continueWithCustomerSignature(signature, true);
                }

                @Override
                public void onCustomerVerificationRequired(TransactionProcess process,
                                                           Transaction transaction) {
                    // always return false here
                    process.continueWithCustomerIdentityVerified(false);
                }

                @Override
                public void onApplicationSelectionRequired(TransactionProcess process,
                                                           Transaction transaction,
                                                           List<ApplicationInformation>
                                                                   applicationInformation) {
                    // This happens only for readers that don't support application selection on their screen
                    process.continueWithSelectedApplication(applicationInformation.get(0));
                }

                @Override
                public void onDccSelectionRequired(TransactionProcess transactionProcess,
                                                   Transaction transaction,
                                                   DccInformation dccInformation) {

                    // This comes up if the DCC selection cannot be done on the terminal itself
                    transactionProcess.continueDccSelectionWithOriginalAmount();

                }

                @Override
                public void onCompleted(TransactionProcess process,
                                        Transaction transaction,
                                        TransactionProcessDetails processDetails) {
                    Log.d("mpos", "completed");

                    if (processDetails.getState() == TransactionProcessDetailsState.APPROVED) {
                            // print the merchant receipt
                            Receipt merchantReceipt = transaction.getMerchantReceipt();
                                                        
                            // print a signature line if required
                            if(merchantReceipt.isSignatureLineRequired()) {
                                    System.out.println("");
                                    System.out.println("");
                                    System.out.println("");
                                    System.out.println("------ PLEASE SIGN HERE ------");
                            }
                                
                            // ask the merchant, whether the shopper wants to have a receipt
                            Receipt customerReceipt = transaction.getCustomerReceipt();
            		
                            // and close the checkout UI
                    } else {
                        // Allow your merchant to try another transaction
                    }
                }
            });
}

@Override
public void onBackPressed() {
    Toast.makeText(this, "The back button is disabled during a transaction. Please use the 'abort' button to cancel the transaction.", Toast.LENGTH_LONG).show();
}

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

Create a button to call the transaction method. In your payment UI, add two TextViews that display the contents of processDetails.getInformation()[0] and  processDetails.getInformation()[1]  each time onStatusChanged is called. This way, the merchant always receives detailed status information about the transaction.

Then, for the Bluetooth Miura reader, pair the reader with your device.

Start the app and tap your button. Follow the instructions on the reader and in the app. Do not worry about charging your card, it is just a test transaction.

Nice! You just processed the first transaction from your app.

Let the Merchant abort the transaction

You have to add a button in the app to enable the merchant to abort the transaction.

For this, add a button in your payment UI. Aborting a transaction is not always possible, e.g. it is not possible to abort it in the last stage of a transaction. Therefore, show/hide your button using the canBeAborted flag in onStatusChanged:

public void onStatusChanged(TransactionProcess process ,
                            Transaction transaction,
                            TransactionProcessDetails processDetails) {
    //..
    abortButton.setVisibility(transaction != null && transaction.canBeAborted() ? View.VISIBLE : View.INVISIBLE);
}

Then, create a click listener for the abort button that aborts the transaction:

public void abort() {
    process.requestAbort();
}

Don't hide the checkout UI directly after the merchant has requested the abort, and don't show text such as 'Aborting...' by yourself. The SDK will call the onCompleted callback once the transaction is aborted. Also, we recommend to let the transaction continue while the app is in the background.

Store Merchant Data on 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. You can create new merchants and get their credentials in the Gateway Manager.

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

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

final TransactionProvider transactionProvider = Mpos.createTransactionProvider(this, 
        <TEST or LIVE, loaded from your backend>, 
        <MerchantIdentifier loaded from your backend>,
        <MerchantSecretKey loaded from your backend>);

Specify the accessory

You have to specify which accessory you want to use with your app and how to connect to it by defining an AccessoryParameters object, which you can create with the provided builder.

The argument which you pass into the builder's constructor specifies the AccessoryFamily - the type of accessory that you want to connect to.

The method, which you call right after the constructor specifies the connection type that you want to use. Currently possible methods are mock(), bluetooth() and tcp().

Different types of accessories can be connected with different methods, wrong configuration will fail when starting the transaction. Also make sure you have included the correct libraries for the accessory and connection type.

After the second method, depending on which connection type you selected, you can set different options specifying the connection. For example, for bluetooth you can select an address prefix which will be applied when searching for the accessory.

Specify the transaction

You have to specify the parameters of the transaction you want to execute with a TransactionParameters object, which you can create with the provided builder.

For charge transactions call charge() method with the amount and currency which you want to use.

Currencies, which you can use for your transactions are limited by the configuration of your Processing Path, wrong currency will fail when executing the transaction.

After the charge() method you can specify additional, optional parameters: