Take payments

October 11, 2024

Perform transactions with a terminal from your Android mobile point-of-sale application.

Importing Android SDK

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

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

Install the following plugins necessary for the SDK to function correctly in your build.gradle file.

plugins {
    id 'kotlin-parcelize'
}

Add the following repositories in your settings.gradle file.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        ...
        maven { url "https://billpocket.jfrog.io/artifactory/billpocket-public-mobile/" }
        maven { url 'https://jitpack.io' }
        maven {
            url 'https://gitlab.com/api/v4/projects/4128550/packages/maven'
        }
    }
}

Initializing SDK

Initialize the SDK by setting your user token and environment via the initSDK() method, as shown below

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

Property	Type	Required	Description	Allowed values
context	Object	Yes	android.content.Context
sdkMode	Object	Yes	InitBillpocketSDK.SdkMode.	`TEST`, `PRODUCTION`
userToken	String	Yes	User token.
listener	Object	Yes	EventListenerInitSDK

Send eventListener as an object that implements the EventListenerInitSDK interface to listen to 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 bluetooth reader

Link the terminal to your mobile device via Bluetooth so the SDK can find it. Get the available readers using the getListBluetoothReaders method.

BluetoothReaderList.getListBluetoothReaders(context, eventListener)

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

override fun resultListReaders(
  readersList: BluetoothDevicesResult<List<BluetoothDevice>>) {
      when(readersList){
          is BluetoothDevicesResult.Success -> {
            //callback if devices are found

            //we suggest you to implement a UI selector
            //iterating through 'readersList.data'
          }
          is BluetoothDevicesResult.Error -> {
            //callback if any error occurred
          }
      }
  }

You will need to verify Bluetooth permissions for devices with an Android API Level lower than 31.

override fun resultListReaders(
  readersList: BluetoothDevicesResult<List<BluetoothDevice>>) {
      when(readersList){
          is BluetoothDevicesResult.Success -> {
            if ((Build.VERSION.SDK_INT >= Build.VERSION_CODES.S)) {
              if ((ActivityCompat.checkSelfPermission(
                this,
                Manifest.permission.BLUETOOTH_CONNECT) ==
                PackageManager.PERMISSION_GRANTED) || (Build.VERSION.SDK_INT >=
                Build.VERSION_CODES.P)) {
                  val reader : BluetoothDevice = readersList.data.get(0)
                  //callback if devices are found
                } else{
                  //Check bluetooth permission
                }
            } else{
              if(readersList.data.isNotEmpty()){
                val reader : BluetoothDevice = readersList.data.get(0)
                //callback if devices are found
              }
            }
          } else{
            val errorMessage : String =readersList.toString()
          }
      }
  }

Implement the connectReader method to get the selected item from the list of available devices. Get the type, macAddress and name data from the previously selected BluetoothDevice object.

BluetoothReaderList.connectReader(context, type, macAddress, name,
eventListener)

Implement the resultReaderConnect method of the EventListenerConection interface to get the connection result.

override fun resultReaderConnect(
  resultConnection: ReaderConnectionResult<DataReader>) {
      when(resultConnection){
          is ReaderConnectionResult.Success -> {
            //callback if connection is successful
          }
          is ReaderConnectionResult.Error -> {
            //callback if connection failed
          } 
      }
}

Request data model

These are all the parameters you can configure when making a request.

Propiedad	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
listener	Object	Yes	Instance of `EventListenerTransaction`.
rotationSignature	Boolean	No	Set `true` to display the signature screen vertically or set `false` to display the signature screen horizontally.

Operations

Discover all the operations available through Terminal SDK integrations.

Sale

Send a request with the required payment settings from your system to a terminal to perform the desired transaction.

Use the doTransaction method to initiate a transaction with the terminal. You must send all required parameters in the request.

BluetoothReaderList.doTransaction(context, amount, description, location, tip, eventListener,rotationSignature)

Send an eventListener object which implements the EventListenerTransaction interface to listen for transaction events.

//called while attempting a connection with the reader
override fun onBeforeTransaction(message: String) { }

//called when obtaining a response from the reader
override fun resultStartTransaction(resultTransaction:
ReaderTransactionResult<String>) {
  when(resultTransaction){
      is ReaderTransactionResult.Success -> {
          //reader is ready for transaction
      }
      is ReaderTransactionResult.Error -> {
          //reader has a communication issue
      } 
    }
}

//called when reader is waiting for a card to execute transaction
override fun onReaderWaitingForCard(message: String) { }

//called when card is in the reader
override fun onCardRead(message: String) { }

Learn how to implement deferred payments, disconnect a terminal, authenticate a transaction, and other available methods in the SDK documentation.

Response

Depending on the result, the response will be returned as one of the following callbacks.

onTransactionSuccessful

This method is called when the transaction is successful.

override fun onTransactionSuccessful(msj: String, transactionData:DataSuccessfulTransaction){
  //code when a transaction is successful
}

onTransactionFinished

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

//callback if transaction had an error
override fun onTransactionFinished(message: String) { }

//callback if transaction is successful
override fun onTransactionSuccessful(message: String, transactionData:
DataSuccessfulTransaction) {
 //transactionData contains all the information about the transaction
}

onTransactionAborted

This callback is called when the operation is cancelled. For example, it is called when the terminal is disconnected or the card reading time has expired.

//called when transaction is aborted
override fun onTransactionAborted(message: String) { }

Please review the SDK reference for more detailed information.

Test data

Make any necessary adjustments to your system using the test data.

Transactions

Get the list of transactions with information relevant to your operations.