Intents de Android

Abre la app de punto de venta (POS) desde tu app móvil de Android para procesar pagos con una terminal.

INFO

Servicio disponible solo en México 🇲🇽.

Requisitos

Para llamar a la app POS desde tu app en un dispositivo Android, debes cumplir con los siguientes requisitos:

Una cuenta válida

La última versión disponible de la app POS de Billpocket instalada desde la Google Play Store

Tener la sesión iniciada en la app POS

Una terminal POS compatible

Agregar el SDK a tu proyecto

Agrega el SDK en el archivo build.gradle de tu proyecto.

Agrega las siguientes dependencias necesarias:

Construir el Intent

Asegúrate de incluir el siguiente import en tu proyecto:

Crea una instancia de la clase BPIntentBuilder y define una acción:

Después, define en la instancia cada parámetro obligatorio u opcional:

enableDialogTip está pendiente de confirmación para este canal

Hoy BPIntentBuilder no tiene un setter documentado para enableDialogTip. Sí está confirmado como campo Boolean para el canal Mobile web (Links) y para extras.enableDialogTip de Cloud Terminal API.

Antes de publicarlo como soportado aquí, confirma con el equipo de ingeniería de BP si existe (o está planeado) un setter para Android intents.

Llamar a la app POS

La app POS debe llamarse de forma implícita desde tu aplicación, con el siguiente action string.

Modelo de datos de la solicitud

Para enviar una solicitud a la terminal, debes enviar un objeto con todas las propiedades requeridas. Abajo está la lista de todas las propiedades disponibles en la solicitud según el tipo de operación.

Propiedad	Tipo	Venta	Reembolso	Descripción
`transaction`	String	Requerido	Requerido	Tipo de transacción: `venta` para una venta o `devolucion` para un reembolso.
`userToken`	String	Requerido	Requerido	Tu user token. Se define con `.setUserToken(...)`. A diferencia de Mobile web (Links), el nombre de la propiedad o del método va en camelCase: aquí no interviene ninguna clave de query string.
`identifier`	String	Requerido	Requerido	Un identificador que generas de tu lado para la trazabilidad de la transacción. Se devuelve en la respuesta. Máximo 256 caracteres.
`amount`	Decimal	Requerido	N/A	Monto de la transacción. No incluye la propina. Dos decimales.
`urlScheme`	String	Requerido	Requerido	App, webhook o URL scheme al que se llama al final de cualquier transacción. Esa app debe estar lista para atender la llamada de la app POS. Máximo 50 caracteres.
`transactionId`	String	N/A	Requerido	ID de la transacción original que generamos nosotros y que se va a reembolsar.
`tip`	Decimal	Opcional	N/A	Propina incluida en la transacción. Dos decimales.
`msi`	Integer	Opcional	N/A	Difiere un pago. Número de meses de diferido: `0` (pago único), `3`, `6`, `9` o `12`.
`reference`	String	Opcional	N/A	Referencia de texto para identificar la transacción. Máximo 256 caracteres.
`email`	String	Opcional	N/A	Correo del cliente (cuando se envía). Máximo 150 caracteres.
`phone`	String	Opcional	N/A	Teléfono del cliente (cuando se envía). Máximo 14 caracteres.
`showPhotoButton`	Boolean	Opcional	N/A	Permite adjuntar una foto durante la transacción. Por defecto `false`.
`mandatoryPhoto`	Boolean	Opcional	N/A	Hace obligatoria la foto durante la transacción. Requiere `showPhotoButton` en `true`.
`deviceToken`	String	Opcional	N/A	Identificador del dispositivo, de tipo string. Se define con `.setDeviceToken(...)`: camelCase, con la misma nota que `userToken` de arriba.
`3pID`	String	Opcional	N/A	Identificador del tercero que solicita la transacción.
`hidePrinter`	Boolean	Opcional	N/A	Indica si se muestra la opción de impresora después de una transacción exitosa. Se define con `.setHidePrinterOption(...)`.
`skipMailPrint`	Boolean	Opcional	N/A	Indica si el ticket se envía automáticamente después de una transacción exitosa. Requiere un correo o un teléfono definido y se salta la pantalla de envío del ticket.
`xpLandscape`	Boolean	Opcional	N/A	Indica si la app POS se abre en modo horizontal. Solo aplica a pantallas grandes.
`deviceName`	String	Opcional	N/A	Nombre para identificar el dispositivo.
`setTimerFinishTRX`	Integer	Opcional	N/A	Temporizador (en segundos) para avanzar a la siguiente pantalla si no hay interacción del usuario en la pantalla de confirmación. Requiere la app POS en versión 4.3.36 o superior y la dependencia billpocket-integration 2.30.0 o superior. Nota: el campo subyacente se llama `timerFinishTRX` (sin `set`) en `extras.timerFinishTRX` de Cloud Terminal API y en el typed extra de Links de la misma funcionalidad; el prefijo `set` de aquí es propio de la nomenclatura de esta tabla, no un campo distinto.
`autoPaymentEnabled`	Boolean	Opcional	N/A	Ponlo en `true` para iniciar el cobro de forma automática, sin presionar el botón Cobrar. Es del mismo tipo que `extras.autoPaymentEnabled` en Cloud Terminal API y que el typed extra que se usa en Mobile web (Links).
`enableDialogTip`	Boolean	Opcional	N/A	Si lo envías en `true` y no mandaste propina (omitida o en $0), el diálogo de propina se muestra durante el checkout. Pendiente de confirmación: consulta la nota de arriba; todavía no está confirmado como setter soportado de `BPIntentBuilder`.

Venta

Llama a la app POS con el siguiente action string:

com.billpocket.payments.START

Inicia la app POS con la función builder, enviando un Intent con todos los parámetros requeridos.

Reembolso

Para usar la funcionalidad de reembolso, asegúrate de incluir el siguiente import en tu proyecto:

Reembolsa una transacción autorizada previamente con un Intent, enviando el ID de la transacción. El reembolso debe hacerse el mismo día de la venta, antes de las 23:00 (22:59:59) hora de CDMX. Consulta todos los parámetros requeridos para reembolsar una transacción.

Nota

Al momento del reembolso, la transacción debe tener 1 minuto o más de autorizada.

Hay dos formas de ejecutar los intents.

Opción 1 — Con validación del ID de la transacción

Usa el servicio de autenticación que verifica la existencia del ID de la transacción:

Esta es la validación del servicio en el listener:

Opción 2 — Intent directo

Envía el intent directamente, sin pasar por el servicio que valida la existencia del ID de la transacción:

Respuesta

La respuesta llega al método onActivityResult de la Activity que hizo la llamada, como un Intent que contiene el resultado de la solicitud de transacción. Puedes parsearlo a un objeto BPPaymentResponse.

Modelo de datos de la respuesta

Según el resultado de la operación, puedes recibir información adicional en las siguientes propiedades:

Propiedad	Tipo	Descripción
`result`	String	Resultado de la operación: `aprobada`, `rechazada` o `error`.
`statusinfo`	String	En caso de error, se devuelve información adicional.
`amount`	Decimal	Monto de la transacción. No incluye la propina.
`tip`	Decimal	Propina incluida en la transacción.
`reference`	String	Referencia de texto para identificar la transacción.
`transactionid`	String	ID de la transacción que generamos nosotros.
`msi`	Integer	Número de meses de diferido a los que se difirió el pago: `0` (pago único), `3`, `6`, `9` o `12`.
`authorization`	String	Autorización que otorga el banco emisor.
`creditcard`	String	Últimos 4 dígitos de la tarjeta.
`cardtype`	String	Tipo de tarjeta.
`email`	String	Correo del cliente (cuando se envía).
`phone`	String	Teléfono del cliente (cuando se envía).
`arqc`	String	Criptograma validado del chip de la tarjeta (cuando está disponible).
`aid`	String	Identificador de aplicación del chip de la tarjeta (cuando está disponible).
`applabel`	String	Etiqueta de aplicación del chip de la tarjeta (cuando está disponible).
`url`	String	Identificador para obtener el comprobante digital.
`identifier`	String	Identificador que enviaste en la venta para la trazabilidad.
`bank`	String	Emisor de la tarjeta.
`accountType`	String	Tipo de cuenta: `credit` (tarjeta de crédito) o `debit` (tarjeta de débito).
`name`	String	Nombre del tarjetahabiente.
`bp_version`	String	Versión de la app POS.

Ajustes de la app POS

Activa o desactiva funcionalidades desde los ajustes de la app POS.

Propinas

Para usar propinas mediante Intents, hay que activar la opción en el menú de ajustes.

Menú de ajustes de la app POS de Billpocket en Android

Activa la opción Propina.

Opción Propina activada en los ajustes de la app POS

Ahora, si envías una transacción con un monto de propina mayor que 0, se muestra una nueva etiqueta debajo del monto de la transacción.

Etiqueta de propina debajo del monto de la transacción en la pantalla de pago

Si no envías monto de propina en la solicitud, o si es igual a 0 y la opción de propina está activada en los ajustes de la app, se muestra el diálogo de propina.

¿Necesitas acceso a la impresora de la terminal?

Consulta la documentación del fabricante.

Recursos

Revisa los siguientes demos y dependencias:

Demo de Android intents

Dependencia GMS

Documentación de la impresora

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

Requisitos#

Agregar el SDK a tu proyecto#

Construir el Intent#

Llamar a la app POS#

Modelo de datos de la solicitud#

Venta#

Reembolso#

Opción 1 — Con validación del ID de la transacción#

Opción 2 — Intent directo#

Respuesta#

Modelo de datos de la respuesta#

Ajustes de la app POS#

Propinas#

Recursos#

Requisitos

Agregar el SDK a tu proyecto

Construir el Intent

Llamar a la app POS

Modelo de datos de la solicitud

Venta

Reembolso

Opción 1 — Con validación del ID de la transacción

Opción 2 — Intent directo

Respuesta

Modelo de datos de la respuesta

Ajustes de la app POS

Propinas

Recursos