Integración de aplicaciones de pago (Inter-App)
En el siguiente documento se especifica como hacer uso de la integración entre aplicaciones móviles para invocar la aplicación de Pagos con sus diferentes parámetros, así como la respuesta que la misma emitirá hacia la aplicación de origen.
Diagrama alto nivel de la integración
Intent
Antes de comenzar
- Para realizar pruebas debes contar con un terminal TUU, ya que la aplicación de Pagos está certificada para operar solo sobre ese modelo en específico.
- SDK de Pagos.. Consideración importante, el nombre del package en develop es diferente al de producción:
com.haulmer.paymentapp.dev y com.haulmer.paymentapp
Parámetros de entrada
{
"amount": 10000,
"tip": 0,
"cashback": 0,
"method": 2,
"installmentsQuantity": 5,
"printVoucherOnApp": true,
"dteType": 48,
"extraData": {
"taxIdnValidation": "8886274-2",
"exemptAmount": 9000,
"netAmount": 1000,
"sourceName": "Nombre App Integradora",
"sourceVersion": "2023.01.20-6",
"customFields": [
{
"name": "nombre",
"value": "valor",
"print": true,
}
]
}
}
| Parámetro | Descripción | Validación de dato |
|---|---|---|
| amount | Monto de la transacción que será usado para cobrar al tarjeta habiente en la app de Pago. amount = netAmount + exemptAmount Nota: No incluye tip ni cashback ya que corresponde a un monto que no se debe declarar. | Su posible valor es cualquier monto superior a 0 que no sea de más de 12 dígitos. |
| tip | Monto de la propina asociada a la transacción. Sus posibles valores son: • -1 cuando no sea utilizado. • 0 para ser solicitado en app de Pago. • Monto mayor a 0. Estas opciones consideran la configuración propia del Terminal para la gestión de la propina. • Si ingresa 0 la app de Pago solo consultará por el monto si está habilitado en su configuración. • Si se usa un valor mayor a 0 se procesará ignorando la configuración del dispositivo. | Puede ser -1, 0 o un número entero mayor a 0. Máximo 12 dígitos. |
| cashback | Monto del vuelto asociado a la transacción. * Solo para venta en débito. * Opciones: • -1 cuando no sea utilizado. • 0 para ser solicitado en app de Pago. • Monto mayor a 0. La opción 0 solo se considerará cuando la configuración del Terminal tenga habilitado el vuelto. | Puede ser -1, 0 o un número entero mayor a 0. Máximo 12 dígitos. |
Parámetros de salida
{
"transactionStatus": true,
"sequenceNumber": "000000004719",
"printerVoucherCommerce": true,
"transactionTip": ,
"extraData": {
...
}
}
| Campo | Descripción |
|---|---|
| transactionStatus | Informa sobre el estado de la transacción. Sus posibles valores son true si es que la transacción termino correctamente o false en caso contrario. |
| sequenceNumber | Correspondiente al número único de la transacción el cual sirve como identificador. Su posible valor es una cadena de texto representando un número de 12 dígitos. |
| printerVoucherCommerce | Indica si la opción de impresión automática del comprobante para el comercio dentro del dispositivo está activa. Sus posible valores son true si esta configurado que se imprima automáticamente el voucher de comercio, false si no está configurado. |
| extraData | Retorna el objeto completo extraData ingresado como parámetros de entrada. |
| transactionTip | Retorna la propina |
| transactionCashback | Retorna el vuelto, esto es dependiente del valor printVoucherOnApp |
Manejo de errores
Cuando exista algún error, ya sea con la validación de los parámetros de entrada o del lado del servidor, se retornará un JSON con la siguiente estructura a la app.
{
"errorCode": 1,
"errorMessage": "La app de pago no soporta propina de acuerdo a sus configuraciones.",
"errorCodeOnApp": 500,
"errorMessageOnApp": "Internal Server Error"
}
El significado de los campos es el siguiente:
| Campo | Descripción | Existencia |
|---|---|---|
| errorCode | Código de error ocurrido. Ver tabla Errores conocidos. | Siempre. |
| errorMessage | Descripción del error. Ver tabla Errores conocidos. | Siempre. |
| errorCodeOnApp | Código de error recibido desde el servidor. | Solo cuando es error del servidor. |
| errorMessageOnApp | Mensaje de error recibido desde el servidor. | Solo cuando es error del servidor. |
Tabla de errores conocidos
| Código | Mensaje | Descripción |
|---|---|---|
| 1 | La app de Pago no soporta propina de acuerdo a sus configuraciones. | |
| 2 | La app de Pago no soporta vuelto de acuerdo a sus configuraciones. | Si el JSON recibido tiene un valor mayor a 0 en el atributo cashback y el Terminal tiene desactivada la opción de vuelto en su configuración establecida en su espacio de trabajo. |
| 3 | El método de pago no esta definido en las configuraciones. | El atributo method del JSON recibido en la aplicación no tiene un valor válido. |
| 4 | El dispositivo no admite cuotas en este tipo de transacción. | Si installmentsQuantity tiene un valor superior a -1 cuando el método seleccionado no sea crédito. |
| 5 | El dispositivo no admite vuelto en este tipo de transacción. | Cuando cashback tenga un valor superior a -1 y el método de transacción elegido no sea débito. |
| 6 | El monto no fue especificado. | En caso que el atributo amount tenga un valor inferior a 0 en el JSON recibido o no viene especificado. |
| 7 | El monto excede el máximo permitido. | En caso de que el atributo amount tenga un valor superior al límite establecido en las configuraciones del Terminal. |
| 8 | No todos los atributos requeridos están presentes. | En caso de que algún atributo no haya sido añadido en el JSON. |
| 9 | Error en proceso de pago. | Error ocurrido durante el proceso de pago en la aplicación. |
| 10 | La transacción fue cancelada. | En caso de que durante el proceso de la transacción esta haya sido cancelada por el usuario. |
| 11 | El Terminal no esta correctamente configurado. | El Terminal aun no ha sido correctamente configurado, esto puede deberse a que aún no ha sido agregado y activado en el espacio de trabajo del usuario, o que el dispositivo no haya sido aprobado desde Backoffice para su uso, o que el dispositivo haya sido previamente deshabilitado. |
| 12 | El dispositivo esta aprobado pero no se han cargado las llaves, favor de abrir la aplicación de pago realizar la inyección de llaves. | El Terminal fue aprobado a través de los ejecutivos de Back Office, sin embargo aún no ha podido descargar y almacenar los certificados y llaves necesarias para su correcto funcionamiento. Es necesario abrir la aplicación para que se lleve a cabo este procedimiento y posteriormente poder hacer uso de la aplicación. |
| 13 | El dispositivo no admite un moto de más de 12 dígitos. | El atributo amount que fue enviado excede el límite de 12 dígitos establecido para el correcto funcionamiento de la aplicación. |
| 14 | El dispositivo no esta conectado a internet. | El Terminal actualmente no esta conectado a alguna red o la red a la cual esta conectado no presenta salida a internet, por lo tanto no es posible cargar las configuraciones. |
| 15 | El dispositivo no pudo obtener la configuración desde su cuenta. | El Terminal está conectado a internet, sin embargo no se pudo establecer conexión con la cuenta de pago correctamente. |
| 16 | El rubro esta en espera de asignación, prontamente podrá ser utilizado. | El canal de pago asociado al POS aun espera su asignación. |
| 17 | El rubro utilizado tuvo un error durante la asignación. | El canal de pago asociado al Terminal experimentó algún error durante su asignación. |
| 18 | El tipo de documento electrónico no esta definido en las configuraciones. | En caso de que el atributo dteType traiga un valor que no esta registrado como un tipo válido. |
| 19 | El RUT indicado no coincide con el utilizado. | Ocurre cuando se envía un RUT en el campo de validación y este no coincide con el utilizado para habilitar la aplicación de Pagos |
| 20 | El SDK de Pagos no se encuentra instalado. | Ocurre cuando el SDK “SunmiPayHardwareService“ no esta instalado o en su defecto no cuenta con una versión igual o superior a 3.3.96. |
| 21 | La aplicación de Pago necesita ser actualizada. | Ocurre cuando la aplicación de pagos rechaza el intent ya que necesita ser actualizada. |
| I-01 | Problemas al procesar campos requeridos. | Si no declara en cada uno de sus customFields “name” o “value“. |
| I-02 | Los campos superan el máximo de caracteres. | Si supera el máximo numero de caracteres por cada Customfield. |
| I-03 | Formato no valido. Posee carácteres reservados del sistema. | Si se incluye los caracteres reservados “&“ y “/“, en alguno de sus Customfield. |
| I-04 | Los campos ingresados no son validos. | Si se ingresan caracteres en blanco tanto como en el "name" o "value". |
Modelo de emisión (S.I.I.)
Ver Comprobante de pago y modelo de emisión.
ChangeLog
Versión 1.3.20221020.0848 [02/11/2022]:
- El campo transactionTip es retornado independiente del valor asociado a printVoucherOnApp.
Updated 3 months ago