Terminal SDK — Android

Accept card-present payments through a Billpocket terminal directly from your Android app. Unlike the App to App integration, the SDK does not require the Billpocket POS app to be installed on the device — your app fully controls the user interface.

INFO

Service available in Mexico only.

Requirements

A valid account

A supported Billpocket terminal

Add the SDK to your project

Dependency

In build.gradle (app level):

INFO

If integrating an Ultra SE reader, add the following permission to AndroidManifest.xml:

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

Required from version 2.8.1 onward for Ultra SE initialization.

Plugins

In build.gradle:

Repositories

In settings.gradle:

Initialize the SDK

Call BillpocketSDK.initSDK() to connect and authenticate.

Parameter	Type	Required	Description	Values
`context`	Object	✅	`android.content.Context`
`sdkMode`	Object	✅	Environment mode	`TEST`, `PRODUCTION`
`userToken`	String	✅	Your user token
`deviceToken`	String	—	Device ID (v2.8.4+). Visible under My Devices in the dashboard
`listener`	Object	✅	`EventListenerInitSDK`

Listen for the result via EventListenerInitSDK:

INFO

initSDK() automatically connects to Ultra and Ultra P terminals — no need to call connectReader() for those models.

Connect a Bluetooth reader

For terminals that connect via Bluetooth (e.g., Nano), discover and connect the reader explicitly.

Get available readers

Implement resultListReaders from EventListenerConnection:

INFO

resultListReaders is not available for Ultra and Ultra P terminals.

Connect the selected reader

Disconnect the reader

Implement onQposDisconnected to handle auto-disconnect after inactivity:

Start a transaction

Use BluetoothReaderTransaction.doTransaction() to initiate a payment.

Parameter	Type	Required	Description
`context`	Object	✅	`android.content.Context`
`amount`	Number	✅	Transaction amount
`description`	String	✅	Transaction description
`location`	Object	✅	`android.location.Location` with lat/lng
`tip`	Number	—	Tip amount
`listener`	Object	✅	`EventListenerTransaction` instance
`rotationSignature`	Boolean	—	`true` = portrait signature, `false` = landscape

Transaction flow callbacks

Magnetic stripe fallback

Multi-application cards

When a card has multiple payment applications, select one:

MSI (Meses Sin Intereses)

For transactions ≥ $300 MXN, onMsiDefined is called with available installment options:

INFO

You must implement onMsiDefined even if you don't offer installments — the last option (installments=0) continues the flow without deferral.

Cardholder authentication

Add the minervacore-gsm-1.0.1.aar dependency and declare the activities in AndroidManifest.xml:

<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"/>

After the activity result, continue:

Signature

Declare the activity:

<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"/>

After the activity result, continue:

Response callbacks

Full EventListenerTransaction interface

Transaction history

Refund

Retrieve the transaction list, then call refundPayment:

Print ticket

Print by transaction ID

Print copy (v2.8.5+)

The requestPrintCopy callback prompts the user to print a copy:

Print result callback

Print bitmap

INFO

For terminal printer documentation, see the Sunmi developer docs.

Message tracking

Optional callbacks for debugging:

Resources

SDK demo app

Android SDK errors

Android SDK release notes

Got a suggestion on this documentation? Contact us.

Terminal SDK

Terminal SDK — Android#

Requirements#

Add the SDK to your project#

Dependency#

Plugins#

Repositories#

Initialize the SDK#

Connect a Bluetooth reader#

Get available readers#

Connect the selected reader#

Disconnect the reader#

Start a transaction#

Transaction flow callbacks#

Magnetic stripe fallback#

Multi-application cards#

MSI (Meses Sin Intereses)#

Cardholder authentication#

PIN#

Signature#

Response callbacks#

Full EventListenerTransaction interface#

Transaction history#

Refund#

Print ticket#

Print by transaction ID#

Print copy (v2.8.5+)#

Print result callback#

Print bitmap#

Message tracking#

Resources#

Terminal SDK — Android

Requirements

Add the SDK to your project

Dependency

Plugins

Repositories

Initialize the SDK

Connect a Bluetooth reader

Get available readers

Connect the selected reader

Disconnect the reader

Start a transaction

Transaction flow callbacks

Magnetic stripe fallback

Multi-application cards

MSI (Meses Sin Intereses)

Cardholder authentication

PIN

Signature

Response callbacks

Full EventListenerTransaction interface

Transaction history

Refund

Print ticket

Print by transaction ID

Print copy (v2.8.5+)

Print result callback

Print bitmap

Message tracking

Resources