SDK for Android

This document describes the SDK integration available for you as a 3rd-Party Developer to communicate and use Billpocket’s API services within your app.

Before any integration, you need to obtain your user token from this link: https://dashboard.billpocket.com. Login into your account and navigate to Integrations (Integraciones), then copy the “token” parameter as shown below.

Billpocket SDK library

In order to use the SDK library you just have to add the following lines to your project’s Gradle:

allprojects {
    repositories {
        ... 
        maven {
            url 'https://billpocket.jfrog.io/artifactory/billpocket-
public-mobile'
              } 
      }
}
dependencies {
    implementation 'com.billpocket:sdk-android:2.7.8.3'
}

SDK Integration - Initializing SDK

The SDK support two modes from InitBillpocketSDK.SdkMode.

TEST. For testing your implementation in a sandbox environment.
PRODUCTION. Use it when you are ready to do real-life transactions.

Init the SDK using the BillpocketSDK.InitSDK method as following:

val sdkMode = InitBillpocketSDK.SdkMode.TEST
val userToken = "yourToken"
BillpocketSDK.initSDK(context, sdkMode, userToken, eventListener)

Provide eventListener as an object implementing the interface EventListenerInitSDK to listen at the initialization result.

override fun resultInitSdk(resultInitSdk: InitSDKResult<String>) {
    when(resultInitSdk){
      is InitSDKResult.Success -> {
        //callback if connection is successful
      }
      is InitSDKResult.Error ->
        //callback if connection resulted in error
      }
}

Connecting with Bluetooth reader

Note: before any connection attempt you must pair the Bluetooth reader to your testing device in order to be found by SDK
First you need to obtain the available readers using BluetoothReaderList.getListBluetoothReaders as following:

Provide eventListener as an object implementing the interface EventListenerConnection to listen at the listing result.

When you receive the data from readersList and choose from one of the corresponding options listed, then you can use BluetoothReaderConnection.connectReader as following:

The type, macAddress and name parameters can be obtained from the previously selected BluetoothDevice object.

Provide eventListener as an object implementing the interface EventListenerConnection to listen at the connection result.

Disconnecting Bluetooth reader
When you need to disconnect from the reader you can use BluetoothReaderConnection.disconnectReader as following:

Provide eventListener as an object implementing the interface EventListenerDisconnection to listen at the disconnection result.

Start a transaction

Before you start a transaction, you need to obtain and coherently validate the following values:

amount: The amount in MXN to be charged from the customer. Must be above 0 to execute the transaction.
description: The description of the transaction i.e: "Purchase". Cannot be empty to execute the transaction.
location: An instance of android.location.Location object, containing latitude and longitude from the transaction's origin. Cannot be null to execute the transaction.
tip: The tip in MXN to be added in the transaction. Must be above or equal to 0 to execute the transaction.

Then, you can use BluetoothReaderTransaction.doTransaction as following:

Provide eventListener as an object implementing the interface EventListenerTransaction to listen at the transaction events. The first events called are the following:

When the reader is ready to execute the transaction, the process can stop at this point to select an MSI (Meses Sin Intereses) option. The callback will provide a list containing all the Q6Descriptor values. We suggest you to let the user choose an option with an UI.

After the selection is made, continue the process calling BluetoothReaderTransaction.continueTransactionWithMSI as following:

Where msi is the selected option from all the available defined.

Next (or if the payment method doesn’t trigger MSI options), the process can stop at this point to request an additional validation.

The first scenario is requesting a PIN, with the callback providing an intent to be launched using startForActivityResult(intent, code) or activityResultLauncher.Launch(intent).

In the result from the activity you must implement BluetoothReaderTransaction.continueTransactionWithPIn(result.data, eventListener), where result.data is the intent form the activity result and eventListener is an instance of EventListenerTransaction.

The second scenario is requesting a signature, with the callback providing an intent to be launched using startForActivityResult (intent, code) or activityResultLauncher.Launch(intent).

In the result from the activity you must implement BluetoothReaderTransaction.continueTransactionWithSignature(result. data), , where result.data is the intent form the activity result.

Following any of these scenarios (or just before onCardRead if none of these were required) the transaction can terminate in success or error. The corresponding callbacks are:

Finally, at any point the transaction can be aborted (i.e. reader abruptly disconnects from device or card is is not inserted in the reader and timeout is triggered). In that case the listener provides the next callback to handle this scenario:

EventListenerTransaction
This interface contains all the events over an transaction:

Refund transaction
To refund a transaction you will first need to request your transaction list as following:

To obtain the result you must implement the method resultHistoryTransaction of the interface EventListenerHistoryTransactions.

Then when you have the transaction list you need to call the method refundPayment as following:

To obtain the result you must implement the method resultRefundPayment of the interface EventListenerRefundPayment

Currently our sdk is already compatible with ultra/ultra with printer readers

For more details, consult the SDK Integration Manual:

https://drive.google.com/file/d/1oAvsS7tzgjZ9McSCvK29K6TN0D52oxuF/view?usp=drive_link

AAR SDK Billpocket

https://drive.google.com/file/d/1S8LdFmPkiMkuIwH6x3UPwSwPyNIp9zbw/view?usp=drive_link

SDK billpocket Project Example

https://drive.google.com/file/d/1JSCK-WxONTYblIhDPz-Ka-jnSUJh7NPv/view?usp=sharing

How to enable debug mode on Billpocket Ultra Devices?