Terminal SDK Android

Accept card-present payments through a terminal directly from your Android app. The Android SDK allows you to communicate securely with a terminal and perform different operations, giving you complete control of the application's user interface.

Unlike the App to App integration, the SDK integration does not require you to have the POS app installed on your device.

INFO

Service available in Mexico 🇲🇽 only.

Requirements

In order to integrate your application through the SDK, you must meet the following requirements:

A valid account

A supported POS terminal

Importing the Android SDK

Import the SDK to your project by adding the following lines to your build.gradle file:

If you are integrating an Ultra SE reader, you need to add the following permission to your AndroidManifest.xml file in order to initialize the SDK correctly:

<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"
    tools:ignore="QueryAllPackagesPermission" />

Note

If you are using a version lower than 2.8.1 and plan to update the SDK version in your app, take note of the permission above to avoid problems initializing the SDK.

Plugins

Install the following plugins, necessary for the correct functioning of the SDK, in your build.gradle file:

Repositories

Add the following repositories in your settings.gradle file:

Initializing the SDK

Initialize the SDK by setting your user token and environment via the initSDK() method.

Property	Type	Required	Description	Allowed values
`context`	Object	YES	`android.content.Context`.
`sdkMode`	Object	YES	`InitBillpocketSDK.SdkMode`.	`TEST`, `PRODUCTION`
`userToken`	String	YES	Your user token.
`deviceToken`	String	NO	Device ID. Available from version 2.8.4 onwards. It can be viewed and renamed from the Billpocket dashboard, My devices section.
`listener`	Object	YES	`EventListenerInitSDK`.

Send eventListener as an object that implements the EventListenerInitSDK interface to listen to the initialization result:

Note

This method also automatically connects to Ultra and Ultra P terminals, so it is not necessary to call the connectReader method for those models.

Connecting a Bluetooth reader

Link the terminal with your mobile device via Bluetooth so that it can be found by the SDK.

Get the available readers using the getListBluetoothReaders method:

Implement the resultListReaders method of the EventListenerConnection interface to listen to the result:

Bluetooth permissions on Android API level lower than 31

For devices with an Android API level lower than 31, you need to verify Bluetooth permissions:

Note

The resultListReaders method is not available for Ultra and Ultra P terminals.

Connect the selected reader

When a reader is selected from the returned options, use the connectReader method. Get the type, macAddress and name parameters from the previously selected BluetoothDevice object.

Implement the resultReaderConnect method of the EventListenerConnection interface to listen to the result of the connection:

Disconnecting a Bluetooth reader

Use the disconnectReader method to disconnect a previously connected Bluetooth reader:

Implement the resultReaderDisconnection method of the EventListenerDisconnection interface to listen to the result of the operation:

Implement the onQposDisconnected method to perform an action when a terminal is turned off after a period of non-use:

Starting a transaction

Use the doTransaction method to start a transaction with the terminal. You must establish the required parameters at the time of making the request.

Property	Type	Required	Description
`context`	Object	YES	`android.content.Context`.
`amount`	Number	YES	Transaction amount.
`description`	String	YES	Transaction description.
`location`	Object	YES	Instance of the `android.location.Location` object with latitude and longitude of the transaction source.
`tip`	Number	NO	Transaction tip (if any).
`listener`	Object	YES	Instance of `EventListenerTransaction`.
`rotationSignature`	Boolean	NO	Set `true` to display the signature screen vertically, or `false` to display it horizontally.

To use this method, make sure to first include the following import:

Send a request to the terminal to start a transaction:

Set eventListener as an object that implements the EventListenerTransaction interface to listen for transaction events:

There are other methods that allow you to cover the different payment flows correctly.

onMagneticCardFound

Called by the SDK to indicate that the card is read using a magnetic stripe, so you must invoke the onContinueTransactionWithMagneticCard() method to continue with the payment flow:

The SDK automatically calls the doOnTransaction method after the invocation of onMagneticCardFound to continue the transaction.

selectAplication

If the read card has more than one payment option, the SDK calls the selectAplication method with the list of available options, so you can select one and continue the operation:

To continue with the transaction, call BluetoothReaderTransaction.continueWithAppIndex(itemSelected) sending the selected option.

Property	Type	Required	Description
`itemSelected`	Integer	YES	Selected item.

Meses sin intereses (MSI)

If the sale is greater than or equal to $300 MXN, the onMsiDefined callback is called with a list of all the available Q6Descriptor options to defer the transaction.

Note

You must implement this callback even if you do not plan to offer the deferred option, in order to continue the payment flow during a transaction.

If you do not want to defer a sale, choose the last option returned from the Q6Descriptor list (Q6Descriptor{installments=0, minAmount=0, commission=0}).

Example of returned Q6Descriptor values

Continue the process by calling the continueTransactionWithMSI method once the correct defer option has been selected:

Property	Type	Required	Description
`msi`	Integer	YES	Selected item.

Cardholder authentication

Perform authentication through the cardholder's Personal Identification Number (PIN) or through an electronic signature to process the transaction. The type of authentication depends on the card.

PIN authentication

To implement this functionality, include the following dependency in your build.gradle file:

You can download the dependency from the Card-present Mexico BP apps repository.

Add the following activities in your AndroidManifest.xml file:

<application
    ...

    <activity
        android:name="com.billpocket.minerva.core.PlainPINCaptureActivity"
        android:excludeFromRecents="true"
        android:exported="false"
        android:permission="com.billpocket.minerva.permission.SECURE_PIN_INPUT"
        android:screenOrientation="portrait"
        android:windowSoftInputMode="stateAlwaysHidden"/>

    <activity
        android:name="com.billpocket.minerva.core.RSAKeyPINCaptureActivity"
        android:excludeFromRecents="true"
        android:exported="false"
        android:permission="com.billpocket.minerva.permission.SECURE_PIN_INPUT"
        android:screenOrientation="portrait"
        android:windowSoftInputMode="stateAlwaysHidden"/>
</application>

Implement the startForActivityResult(intent, code) or activityResultLauncher.Launch(intent) callback to perform PIN authentication:

Implement the function BluetoothReaderTransaction.continueTransactionWithPIn(result.data, eventListener) to get the result of the activity.

Property	Type	Required	Description
`result.data`	Object	YES	Intent from the activity result.
`listener`	Object	YES	Instance of `EventListenerTransaction`.

Signature authentication

Add the following activity in your AndroidManifest.xml file:

<application
    ...

    <activity
        android:name="com.billpocket.bil_lib.SignatureActivity"
        android:excludeFromRecents="true"
        android:exported="false"
        android:permission="com.billpocket.minerva.permission.SECURE_PIN_INPUT"
        android:screenOrientation="portrait"
        android:windowSoftInputMode="stateAlwaysHidden"/>
</application>

Implement the startForActivityResult(intent, code) or activityResultLauncher.Launch(intent) callback to perform electronic signature authentication:

Implement the function BluetoothReaderTransaction.continueTransactionWithSignature(result.data) to get the result of the activity.

Property	Type	Required	Description
`result.data`	Object	YES	Intent from the activity result.

Response callbacks

A transaction can result in success or error depending on the result. Below is the list of available callbacks.

onTransactionSuccessful

Called when the transaction is successful. transactionData contains all the information about the transaction.

onTransactionFinished

Called when a magnetic stripe payment is made or an error has occurred during the transaction.

onTransactionAborted

If the operation is aborted — for example, the terminal was disconnected or a card read timed out — the onTransactionAborted callback is executed to indicate the result of the operation.

EventListenerTransaction

Below is the list of events available for a transaction.

Get transaction list

Get the list of previous transactions via the getHistoryTransaction method:

The result is returned in the resultHistoryTransaction callback of the EventListenerHistoryTransactions interface:

Refund

Select a transaction from the list of authorized transactions in order to perform a refund:

Implement the resultHistoryTransaction method of the EventListenerHistoryTransactions interface:

Call the refundPayment method to perform a refund:

Implement the resultRefundPayment method of the EventListenerRefundPayment interface to get the result:

Print ticket

Print by transaction ID

To print the purchase ticket, call the printTicket method:

Print ticket copy

Starting from version 2.8.5, the requestPrintCopy callback is used to prompt the user with a dialog asking whether they want to print a copy of the ticket.

requestPrintCopy() calls continueWithPrintTicketCopy with either true (print) or false (skip printing), based on the user's selection:

Implementation example:

Print result

Implement the onResult callback of the EventListenerPrinter interface to get the response from the operation:

Print a bitmap

You can print a ticket by sending a bitmap via the printTicketImage method:

The response is returned through the same onResult callback of the EventListenerPrinter interface.

Do you need access to the terminal printer?

Check the manufacturer's documentation.

Message tracking

Implement the following optional methods to obtain more information while using the SDK.

Transaction

Method for obtaining information during a transaction:

SDK init

Method to obtain information during the SDK initialization process:

Reader connection

Method to obtain information during the connection process with a terminal:

Resources

SDK demo

Android SDK errors

Got a suggestion on this documentation? Contact us.

Requirements#

Importing the Android SDK#

Plugins#

Repositories#

Initializing the SDK#

Connecting a Bluetooth reader#

Bluetooth permissions on Android API level lower than 31#

Connect the selected reader#

Disconnecting a Bluetooth reader#

Starting a transaction#

onMagneticCardFound#

selectAplication#

Meses sin intereses (MSI)#

Cardholder authentication#

PIN authentication#

Signature authentication#

Response callbacks#

onTransactionSuccessful#

onTransactionFinished#

onTransactionAborted#

EventListenerTransaction#

Get transaction list#

Refund#

Print ticket#

Print by transaction ID#

Print ticket copy#

Print result#

Print a bitmap#

Message tracking#

Transaction#

SDK init#

Reader connection#

Resources#

Requirements

Importing the Android SDK

Plugins

Repositories

Initializing the SDK

Connecting a Bluetooth reader

Bluetooth permissions on Android API level lower than 31

Connect the selected reader

Disconnecting a Bluetooth reader

Starting a transaction

onMagneticCardFound

selectAplication

Meses sin intereses (MSI)

Cardholder authentication

PIN authentication

Signature authentication

Response callbacks

onTransactionSuccessful

onTransactionFinished

onTransactionAborted

EventListenerTransaction

Get transaction list

Refund

Print ticket

Print by transaction ID

Print ticket copy

Print result

Print a bitmap

Message tracking

Transaction

SDK init

Reader connection

Resources