App a app — iOS - Kushki Developer Portal

Abre la app de punto de venta (POS) desde tu app móvil de iOS para procesar pagos con una terminal. La app POS se llama mediante un custom URL scheme.

INFO

Servicio disponible solo en México 🇲🇽.

Requisitos

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

Una cuenta válida

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

Tener la sesión iniciada en la app POS

Un lector de Billpocket compatible

Llamar a la app POS

La app POS usa el custom URL scheme billpocket:// para recibir solicitudes de otras apps. Puedes enviar parámetros en la solicitud para configurar la operación que quieres realizar. Cuando recibe una solicitud, la app se abre en la pantalla que corresponde según la configuración enviada.
Puedes realizar las siguientes operaciones:

Venta

Reembolso

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. 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 custom URL schemes.
`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`.
`comesFromQR`	Boolean	Opcional	N/A	Ponlo en `true` si la URL de la transacción viene de una imagen QR.

Venta

Envía una solicitud de venta desde tu app al POS para procesar un pago con una terminal.
Para hacer una solicitud de venta debes:

Poner la propiedad transaction en el valor venta.

Enviar tu user token.

Enviar un identifier generado de tu lado para la trazabilidad. Se devuelve en la respuesta.

Enviar un monto válido.

Enviar un urlScheme donde se devolverá la respuesta.
También puedes definir una propina, diferir un pago y otras operaciones. Consulta el modelo de datos de la solicitud para ver todos los parámetros disponibles en la solicitud.
Los parámetros deben concatenarse en un query string junto con el custom URL scheme billpocket://.

Importante

Debes asegurarte de codificar correctamente los parámetros antes de hacer una solicitud.

Ejemplo de solicitud de venta

En este ejemplo, los valores necesarios para la solicitud se obtienen de campos de texto para concatenarlos a la URL.

Los valores de NSString se concatenan y se convierten a NSURL para formar una URL válida.
Para concatenar NSString, usa stringWithFormat como se muestra abajo.

Abre la URL con el método open().

Si la solicitud fue exitosa, la app POS se muestra en la pantalla de pago con la configuración enviada.

Reembolso

Envía una solicitud desde tu app para procesar un reembolso.
Para hacer un reembolso debes:

Poner la propiedad transaction en el valor devolucion.

Enviar tu user token.

Enviar un identifier generado de tu lado para la trazabilidad. Se devuelve en la respuesta.

Enviar un monto válido.

Enviar un urlScheme donde se devolverá la respuesta.

Enviar el ID de la transacción que se va a reembolsar.
Revisa el modelo de datos de la solicitud.
Los parámetros deben concatenarse en un query string junto con el custom URL scheme billpocket://. Debes asegurarte de codificar correctamente los parámetros antes de solicitar un reembolso.

Condiciones del reembolso

Para poder reembolsarse, una transacción debe cumplir con las siguientes condiciones:

La transacción original debe llevar aprobada al menos 1 minuto.

La solicitud debe hacerse antes de las 11 p.m. (hora de CDMX) del mismo día en que se hizo la transacción original.

El reembolso debe ser por un monto igual o menor al de la transacción original.

Nota

Para procesar un reembolso en iOS necesitas la app POS en versión 4.3.24 o superior.

Ejemplo de solicitud de reembolso

Para concatenar NSString, usa stringWithFormat como se muestra abajo.

URLWithString se usa para castear la respuesta NSURL.

Abre la URL con el método open().

Si la solicitud fue exitosa, la app POS se muestra en la pantalla de pago con la configuración enviada.

Respuesta

Averigua si la solicitud fue aprobada (aprobada), rechazada (rechazada) o si hubo un error (error) con la propiedad result que se devuelve en la respuesta.
La respuesta se envía junto con los parámetros de la operación a la URL que definiste en la propiedad urlScheme. El payload viene codificado como query string, así que tiene una estructura parecida a la de la solicitud. Debes procesar la respuesta correctamente para continuar con el flujo de pago.
Entre los parámetros importantes que se devuelven está la propiedad transactionId, que contiene el ID de la transacción aprobada y te permite realizar otras operaciones, como un reembolso.

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.

Ejemplo de una respuesta

myapp://result=aprobada&statusinfo=&amount=100.00&tip=15.00&reference=Pago%20%26%20%25%20%23%20(%20)%20/%20@%20con%20propina%20a%203%20meses%20sin%20intereses&transactionid=72037…

Puedes implementar un Custom URL Scheme o un Universal Link para manejar la respuesta en tu aplicación. Consulta la documentación de Apple sobre cómo definir un custom URL scheme y cómo permitir que las apps y los sitios web enlacen a tu contenido.

Consulta también

Descubre cómo configurar un splash screen al llamar a la app POS.

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

App a app — iOS

Requisitos#

Llamar a la app POS#

Modelo de datos de la solicitud#

Venta#

Ejemplo de solicitud de venta#

Si la solicitud fue exitosa, la app POS se muestra en la pantalla de pago con la configuración enviada.#

Reembolso#

Condiciones del reembolso#

Ejemplo de solicitud de reembolso#

Si la solicitud fue exitosa, la app POS se muestra en la pantalla de pago con la configuración enviada.#

Respuesta#

Modelo de datos de la respuesta#

Ejemplo de una respuesta#

Puedes implementar un Custom URL Scheme o un Universal Link para manejar la respuesta en tu aplicación. Consulta la documentación de Apple sobre cómo definir un custom URL scheme y cómo permitir que las apps y los sitios web enlacen a tu contenido.#

Consulta también#

Descubre cómo configurar un splash screen al llamar a la app POS.#

Requisitos

Llamar a la app POS

Modelo de datos de la solicitud

Venta

Ejemplo de solicitud de venta

Si la solicitud fue exitosa, la app POS se muestra en la pantalla de pago con la configuración enviada.

Reembolso

Condiciones del reembolso

Ejemplo de solicitud de reembolso

Si la solicitud fue exitosa, la app POS se muestra en la pantalla de pago con la configuración enviada.

Respuesta

Modelo de datos de la respuesta

Ejemplo de una respuesta

Puedes implementar un Custom URL Scheme o un Universal Link para manejar la respuesta en tu aplicación. Consulta la documentación de Apple sobre cómo definir un custom URL scheme y cómo permitir que las apps y los sitios web enlacen a tu contenido.

Consulta también

Descubre cómo configurar un splash screen al llamar a la app POS.