Terminal SDK Android

Acepta pagos presenciales a través de una terminal directamente desde tu app de Android. El SDK de Android te permite comunicarte de forma segura con una terminal y ejecutar distintas operaciones, con control total de la interfaz de usuario de tu aplicación.

A diferencia de la integración App to App, la integración por SDK no requiere que tengas instalada la app POS en tu dispositivo.

INFO

Servicio disponible solo en México 🇲🇽.

Requisitos

Para integrar tu aplicación mediante el SDK, debes cumplir los siguientes requisitos:

Una cuenta válida

Una terminal POS compatible

Importar el SDK de Android

Importa el SDK a tu proyecto agregando las siguientes líneas a tu archivo build.gradle:

Si vas a integrar un lector Ultra SE, debes agregar el siguiente permiso a tu archivo AndroidManifest.xml para inicializar el SDK correctamente:

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

Nota

Si usas una versión anterior a 2.8.1 y planeas actualizar la versión del SDK en tu app, ten en cuenta el permiso anterior para evitar problemas al inicializar el SDK.

Plugins

Instala en tu archivo build.gradle los siguientes plugins, necesarios para el correcto funcionamiento del SDK:

Repositorios

Agrega los siguientes repositorios en tu archivo settings.gradle:

Inicializar el SDK

Inicializa el SDK indicando tu user token y el ambiente mediante el método initSDK().

Propiedad	Tipo	Obligatorio	Descripción	Valores permitidos
`context`	Object	SÍ	`android.content.Context`.
`sdkMode`	Object	SÍ	`InitBillpocketSDK.SdkMode`.	`TEST`, `PRODUCTION`
`userToken`	String	SÍ	Tu user token.
`deviceToken`	String	NO	ID del dispositivo. Disponible a partir de la versión 2.8.4. Puedes verlo y renombrarlo desde el dashboard de Billpocket, en la sección My devices.
`listener`	Object	SÍ	`EventListenerInitSDK`.

Envía eventListener como un objeto que implemente la interfaz EventListenerInitSDK para escuchar el resultado de la inicialización:

Nota

Este método también conecta automáticamente las terminales Ultra y Ultra P, así que no es necesario llamar al método connectReader para esos modelos.

Conectar un lector Bluetooth

Vincula la terminal con tu dispositivo móvil por Bluetooth para que el SDK pueda encontrarla.

Obtén los lectores disponibles con el método getListBluetoothReaders:

Implementa el método resultListReaders de la interfaz EventListenerConnection para escuchar el resultado:

Permisos de Bluetooth en Android con API level inferior a 31

En dispositivos con un API level de Android inferior a 31, debes verificar los permisos de Bluetooth:

Nota

El método resultListReaders no está disponible para las terminales Ultra y Ultra P.

Conectar el lector seleccionado

Cuando selecciones un lector entre las opciones devueltas, usa el método connectReader. Obtén los parámetros type, macAddress y name del objeto BluetoothDevice que seleccionaste antes.

Implementa el método resultReaderConnect de la interfaz EventListenerConnection para escuchar el resultado de la conexión:

Desconectar un lector Bluetooth

Usa el método disconnectReader para desconectar un lector Bluetooth conectado previamente:

Implementa el método resultReaderDisconnection de la interfaz EventListenerDisconnection para escuchar el resultado de la operación:

Implementa el método onQposDisconnected para ejecutar una acción cuando una terminal se apaga tras un periodo de inactividad:

Iniciar una transacción

Usa el método doTransaction para iniciar una transacción con la terminal. Debes establecer los parámetros obligatorios al momento de hacer la solicitud.

Propiedad	Tipo	Obligatorio	Descripción
`context`	Object	SÍ	`android.content.Context`.
`amount`	Number	SÍ	Monto de la transacción.
`description`	String	SÍ	Descripción de la transacción.
`location`	Object	SÍ	Instancia del objeto `android.location.Location` con la latitud y la longitud del origen de la transacción.
`tip`	Number	NO	Propina de la transacción (si aplica).
`listener`	Object	SÍ	Instancia de `EventListenerTransaction`.
`rotationSignature`	Boolean	NO	Usa `true` para mostrar la pantalla de firma en vertical o `false` para mostrarla en horizontal.

Para usar este método, asegúrate de incluir primero el siguiente import:

Envía una solicitud a la terminal para iniciar una transacción:

Define eventListener como un objeto que implemente la interfaz EventListenerTransaction para escuchar los eventos de la transacción:

Existen otros métodos que te permiten cubrir correctamente los distintos flujos de pago.

onMagneticCardFound

El SDK lo llama para indicar que la tarjeta se leyó por banda magnética, así que debes invocar el método onContinueTransactionWithMagneticCard() para continuar con el flujo de pago:

El SDK llama automáticamente al método doOnTransaction después de invocar onMagneticCardFound para continuar la transacción.

selectAplication

Si la tarjeta leída tiene más de una opción de pago, el SDK llama al método selectAplication con la lista de opciones disponibles para que selecciones una y continúes la operación:

Para continuar con la transacción, llama a BluetoothReaderTransaction.continueWithAppIndex(itemSelected) enviando la opción seleccionada.

Propiedad	Tipo	Obligatorio	Descripción
`itemSelected`	Integer	SÍ	Elemento seleccionado.

Meses Sin Intereses (MSI)

Si la venta es mayor o igual a $300 MXN, se llama al callback onMsiDefined con la lista de todas las opciones Q6Descriptor disponibles para diferir la transacción.

Nota

Debes implementar este callback aunque no planees ofrecer la opción de diferido, para poder continuar el flujo de pago durante una transacción.

Si no quieres diferir una venta, elige la última opción devuelta en la lista Q6Descriptor (Q6Descriptor{installments=0, minAmount=0, commission=0}).

Ejemplo de valores Q6Descriptor devueltos

Continúa el proceso llamando al método continueTransactionWithMSI una vez que hayas seleccionado la opción de diferido correcta:

Propiedad	Tipo	Obligatorio	Descripción
`msi`	Integer	SÍ	Elemento seleccionado.

Autenticación del tarjetahabiente

Autentica al tarjetahabiente con su número de identificación personal (PIN) o con una firma electrónica para procesar la transacción. El tipo de autenticación depende de la tarjeta.

Autenticación con PIN

Para implementar esta funcionalidad, incluye la siguiente dependencia en tu archivo build.gradle:

Puedes descargar la dependencia del repositorio Card-present Mexico BP apps.

Agrega las siguientes activities en tu archivo AndroidManifest.xml:

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

Implementa el callback startForActivityResult(intent, code) o activityResultLauncher.Launch(intent) para realizar la autenticación con PIN:

Implementa la función BluetoothReaderTransaction.continueTransactionWithPIn(result.data, eventListener) para obtener el resultado de la activity.

Propiedad	Tipo	Obligatorio	Descripción
`result.data`	Object	SÍ	Intent del resultado de la activity.
`listener`	Object	SÍ	Instancia de `EventListenerTransaction`.

Autenticación con firma

Agrega la siguiente activity en tu archivo AndroidManifest.xml:

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

Implementa el callback startForActivityResult(intent, code) o activityResultLauncher.Launch(intent) para realizar la autenticación con firma electrónica:

Implementa la función BluetoothReaderTransaction.continueTransactionWithSignature(result.data) para obtener el resultado de la activity.

Propiedad	Tipo	Obligatorio	Descripción
`result.data`	Object	SÍ	Intent del resultado de la activity.

Callbacks de respuesta

Una transacción puede terminar en success o error según el resultado. Esta es la lista de callbacks disponibles.

onTransactionSuccessful

Se llama cuando la transacción es exitosa. transactionData contiene toda la información de la transacción.

onTransactionFinished

Se llama cuando se realiza un pago con banda magnética o cuando ocurre un error durante la transacción.

onTransactionAborted

Si la operación se aborta —por ejemplo, porque la terminal se desconectó o se agotó el tiempo de lectura de la tarjeta—, se ejecuta el callback onTransactionAborted para indicar el resultado de la operación.

EventListenerTransaction

Esta es la lista de eventos disponibles para una transacción.

Obtener la lista de transacciones

Obtén la lista de transacciones previas con el método getHistoryTransaction:

El resultado se devuelve en el callback resultHistoryTransaction de la interfaz EventListenerHistoryTransactions:

Reembolso

Selecciona una transacción de la lista de transacciones autorizadas para realizar un reembolso:

Implementa el método resultHistoryTransaction de la interfaz EventListenerHistoryTransactions:

Llama al método refundPayment para realizar el reembolso:

Implementa el método resultRefundPayment de la interfaz EventListenerRefundPayment para obtener el resultado:

Imprimir el ticket

Imprimir por ID de transacción

Para imprimir el ticket de compra, llama al método printTicket:

Imprimir una copia del ticket

A partir de la versión 2.8.5, el callback requestPrintCopy muestra al usuario un diálogo que le pregunta si quiere imprimir una copia del ticket.

requestPrintCopy() llama a continueWithPrintTicketCopy con true (imprimir) o false (no imprimir), según lo que elija el usuario:

Ejemplo de implementación:

Resultado de la impresión

Implementa el callback onResult de la interfaz EventListenerPrinter para obtener la respuesta de la operación:

Imprimir un bitmap

Puedes imprimir un ticket enviando un bitmap con el método printTicketImage:

La respuesta se devuelve a través del mismo callback onResult de la interfaz EventListenerPrinter.

¿Necesitas acceso a la impresora de la terminal?

Consulta la documentación del fabricante.

Seguimiento de mensajes

Implementa los siguientes métodos opcionales para obtener más información durante el uso del SDK.

Transacción

Método para obtener información durante una transacción:

Inicialización del SDK

Método para obtener información durante el proceso de inicialización del SDK:

Conexión del lector

Método para obtener información durante el proceso de conexión con una terminal:

Recursos

Demo del SDK

Errores del SDK de Android

¿Tienes una sugerencia sobre esta documentación? Contáctanos.

Requisitos#

Importar el SDK de Android#

Plugins#

Repositorios#

Inicializar el SDK#

Conectar un lector Bluetooth#

Permisos de Bluetooth en Android con API level inferior a 31#

Conectar el lector seleccionado#

Desconectar un lector Bluetooth#

Iniciar una transacción#

onMagneticCardFound#

selectAplication#

Meses Sin Intereses (MSI)#

Autenticación del tarjetahabiente#

Autenticación con PIN#

Autenticación con firma#

Callbacks de respuesta#

onTransactionSuccessful#

onTransactionFinished#

onTransactionAborted#

EventListenerTransaction#

Obtener la lista de transacciones#

Reembolso#

Imprimir el ticket#

Imprimir por ID de transacción#

Imprimir una copia del ticket#

Resultado de la impresión#

Imprimir un bitmap#

Seguimiento de mensajes#

Transacción#

Inicialización del SDK#

Conexión del lector#

Recursos#

Requisitos

Importar el SDK de Android

Plugins

Repositorios

Inicializar el SDK

Conectar un lector Bluetooth

Permisos de Bluetooth en Android con API level inferior a 31

Conectar el lector seleccionado

Desconectar un lector Bluetooth

Iniciar una transacción

onMagneticCardFound

selectAplication

Meses Sin Intereses (MSI)

Autenticación del tarjetahabiente

Autenticación con PIN

Autenticación con firma

Callbacks de respuesta

onTransactionSuccessful

onTransactionFinished

onTransactionAborted

EventListenerTransaction

Obtener la lista de transacciones

Reembolso

Imprimir el ticket

Imprimir por ID de transacción

Imprimir una copia del ticket

Resultado de la impresión

Imprimir un bitmap

Seguimiento de mensajes

Transacción

Inicialización del SDK

Conexión del lector

Recursos