App a app — web móvil - Kushki Developer Portal

Abre la app de punto de venta (POS) desde una app nativa o web móvil en Android, con custom URL schemes, para procesar pagos con una terminal.

INFO

Servicio disponible solo en México 🇲🇽.

Requisitos

Para llamar a la app POS desde una aplicación web móvil 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 en Android

Un lector de Billpocket compatible

Llamar a la app POS

Reúne y envía en la URL, como query string, todos los parámetros string y decimal requeridos cuando llames a la app POS para hacer una operación con una terminal. La app POS se muestra cuando abres un link con el custom URL scheme Billpocket://. La transacción se configura según los parámetros que recibe en la llamada.

Los parámetros Boolean e Integer no se leen del query string

La app POS interpreta los valores Boolean e Integer como tipos nativos. Un query string de URL solo puede transportar texto, así que esos parámetros no se leen de forma confiable si solo viajan en la URL.

Para usar cualquiera de los parámetros de Extras tipados del Intent, adjúntalos como extras tipados del Intent de Android (Intent.putExtra(...)) en el mismo intent ACTION_VIEW que abre la URI billpocket:// — consulta el ejemplo nativo de Android más abajo.

Operaciones disponibles

Venta

Reembolso

Modelo de datos de la solicitud

Para enviar una solicitud a la terminal, debes enviar un objeto con todas las propiedades requeridas. Las propiedades están separadas en dos grupos, porque viajan por dos mecanismos distintos en la misma llamada.

Datos del query string

Parámetros String y Decimal. Envíalos en el query string de la URL billpocket://, con la clave exacta que aparece en la columna Propiedad de abajo.

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. La clave del query string va en minúsculas. Este mismo valor se llama `userToken` (camelCase) en Android intents y en el SDK: la app POS no reconoce la clave en camelCase en los links.
`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.
`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.
`devicetoken`	String	Opcional	N/A	Identificador del dispositivo, de tipo string. La clave del query string va en minúsculas. Este mismo valor se llama `deviceToken` (camelCase) en Android intents y en el SDK.
`3pID`	String	Opcional	N/A	Identificador del tercero que solicita la transacción.
`deviceName`	String	Opcional	N/A	Nombre para identificar el dispositivo.

Extras tipados del Intent

Parámetros Boolean e Integer. Envíalos como extras tipados en el Intent que abre la URL billpocket://, no como texto del query string. Consulta Venta desde una app nativa de Android.

Propiedad	Tipo	Venta	Reembolso	Descripción
`msi`	Integer	Opcional	N/A	Difiere un pago. Número de meses de diferido: `0` (pago único), `3`, `6`, `9` o `12`.
`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`.
`hidePrinter`	Boolean	Opcional	N/A	Indica si se muestra la opción de impresora después de una transacción exitosa.
`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.
`enableDialogTip`	Boolean	Opcional	N/A	Ponlo en `true` para mostrar el diálogo de propina durante el checkout. Para que el diálogo se muestre, `tip` debe omitirse o enviarse con el valor `0`.
`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 se usa en Android intents y que `extras.autoPaymentEnabled` de Cloud Terminal API.
`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. La clave del extra tipado es `timerFinishTRX` (sin `set`): coincide con `extras.timerFinishTRX` de Cloud Terminal API y con la implementación de referencia de Android.

Importante

Los booleanos deben enviarse como true / false, nunca como 1 / 0.

Venta

Este es un ejemplo de cómo llamar a la app POS con un custom URL scheme en Android para hacer una venta. Cubre solo los parámetros String y Decimal: úsalo desde una página web móvil o un WebView.

Venta desde una app nativa de Android

Una llamada de navegador con window.location.replace(...) no puede adjuntar extras tipados del Intent: para eso hace falta que una app nativa de Android construya el Intent directamente. Usa este patrón siempre que la venta necesite algún parámetro Boolean o Integer de Extras tipados del Intent:

Si la información que enviaste es correcta, la app POS se abre en la pantalla de pago con la configuración definida para la transacción. Sigue los pasos en pantalla para completar el cobro con la terminal.

Reembolso

Este es un ejemplo de cómo llamar a la app POS con un custom URL scheme en Android para hacer un reembolso:

Chrome intents

También puedes crear un Intent desde una aplicación web que corre en Chrome para iniciar la integración con una instancia instalada de la app POS.

Nota

Las integraciones por Chrome intents no devuelven la respuesta por un callback de URL. Para obtener la respuesta, puedes implementar un webhook que reciba los eventos en tu aplicación.

Consulta la referencia de Android Intents con Chrome para más información.

Ajustes de la app POS en Android

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.

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. Es el mismo comportamiento que activa enableDialogTip.

Respuesta

Recibe la respuesta de una solicitud por un callback de URL. La respuesta se devuelve con custom URL schemes. El callback de URL debe procesar correctamente las solicitudes con la respuesta de la operación.

Puedes usar un custom URL scheme en la URL de callback. Tendrás que registrar tu custom URL scheme dentro de tu aplicación para que pueda atender las solicitudes entrantes. Revisa la documentación de Android sobre cómo registrar custom URL schemes.

Este es un ejemplo de respuesta a un custom URL scheme:

myApp://identifier=bpTRX&amount=10.00&authorization=BP6602&result=aprobada&reference=Venta%2520-%2520B99773E6BA6&creditcard=3292&cardtype=MASTERCARD&aid=A0000000041010&tip=1.01&url=68a30855f20923fc0d20eeaeee11061a62ab0eec&arqc=3C2A4D155F23AA81&bank=Bancomer%2520%252F%2520Banamex&name=%2520PERFIL%2520EJECUTIVO%252FPRG%2520%2520%2520%2520%2520&bp_version=4.3.0&transactionid=111029&accountType=DEBIT&applabel=Debit%2520Mastercard

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.

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

App a app — web móvil

Requisitos#

Llamar a la app POS#

Operaciones disponibles#

Modelo de datos de la solicitud#

Datos del query string#

Extras tipados del Intent#

Venta#

Venta desde una app nativa de Android#

Reembolso#

Chrome intents#

Ajustes de la app POS en Android#

Propinas#

Respuesta#

Modelo de datos de la respuesta#

Requisitos

Llamar a la app POS

Operaciones disponibles

Modelo de datos de la solicitud

Datos del query string

Extras tipados del Intent

Venta

Venta desde una app nativa de Android

Reembolso

Chrome intents

Ajustes de la app POS en Android

Propinas

Respuesta

Modelo de datos de la respuesta