Integración CAJA POS - Android
Tabla de Contenido
1 Tabla de Contenido
2 CONCEPTO
3 VERSION ACTUAL
4 IMPLEMENTACIÓN DE LA API REST
5 MIGRACIÓN DE LA SOLUCIÓN CAJAPOS CON SDK A POS ANDROID
6 SERVICIOS REST DISPONIBLES
6.1 Solicitud Venta Contado
6.2 Solicitud Venta Cuotas
6.3 Solicitud Venta Forzado Débito
6.4 Solicitud Venta Forzado Crédito
6.5 Envío de Monto
6.6 Verificación de conexión de POS - Mensaje ECO
7 TABLA DE ISSUER ID's
CONCEPTO
Con el objetivo de dotar de una mayor seguridad y generar un nuevo ecosistema de aplicaciones y experiencias con el uso de los POS, Bancard presenta
un nuevo producto de POS basado en terminales Android.
La integración CajaPOS entre los sistemas de facturación y las nuevas terminales Android se realizará a través de la red interna del comercio, utilizando
servicios REST como protocolo de intercambio de mensajes.
A continuación vemos una imagen del funcionamiento de la integración POS Android.
VERSION ACTUAL
La versión de la API REST implementada en el POS es la 1.5.0.
IMPLEMENTACIÓN DE LA API REST
El software de facturación se comunicará con el POS Android a través de servicios REST que estarán publicados en el POS.
Se deberá desarrollar en el sistema de facturación los servicios necesarios para poder establecer la comunicación hacia el POS como se describen
en la sección SERVICIOS REST DISPONIBLES.
Los desarrolladores podrán realizar sus pruebas de integración utilizando un software cliente de su preferencia (Ej. Postman), a través de la dirección
IP que el POS tiene asignado y el puerto de escucha 3000.
MIGRACIÓN DE LA SOLUCIÓN CAJAPOS CON SDK A POS ANDROID
Para aquellos comercios que ya han implementado la solución CajaPOS con el SDK, el único cambio necesario para utilizar el sistema de facturación
con el POS Android será reemplazar en este la IP de conexión del "SDK" por la IP del POS que el punto de acceso inalámbrico le asigna, previos
ajustes a nivel de red para asegurar la comunicación TCP/IP entre ambas terminales.
SERVICIOS REST DISPONIBLES
La forma de comunicación con el POS será a través de peticiones REST. Se cuenta con dos opciones de venta.
Solicitud Venta Contado: Opción utilizada para realizar pago al contado y descuentos por BIN si los hubiera (no discrimina tipo de tarjeta
se realiza la transacción en un solo pago).
Solicitud Venta Cuotas: Opción utilizada para venta en cuotas.
Luego de obtener la respuesta del servicio solicitado se envía el monto a cobrar al siguiente servicio:
Envio del Monto: Opción para enviar Descuento o Monto de Transacción si no hubiera descuento por BIN.
También se tiene una llamada para verificar si el POS se encuentra conectado.
Mensaje Eco: Esta opción podría servir para agregar antes de hacer un pedido de venta y asegurarnos que el POS se encuentre conectado.
Solicitud Venta Contado
Método POST
URL IP:PORT/pos/venta-ux
JSON Entrada
Body
{
"facturaNro": 123456789,
"monto": 50000
}
Donde:
facturaNro: int(12) Corresponde al número de factura generado por el sistema.
monto: int(12) es el valor del monto inicial de la transacción mayor a 0.
Success HTTP/1.1 200 OK
Response
Body
{
"bin": "9999999999",
"nsu": "999999"
}
Donde:
bin: string(10) Corresponde al número BIN de la tarjeta asociada a la operación. Se puede utilizar este valor para realizar
descuentos según el tipo de tarjeta.
nsu: string(6) Código de operación interna del POS. Este número debe ser enviado junto con el monto en el servicio de En
vío de monto.
Una vez recibido los datos del Servicio se envía el monto a cobrar y el nsu al servicio de Envío de monto
Error Status 500 : Error interno del POS
Response
Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra
Body
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
Solicitud Venta Cuotas
Método POST
URL IP:PORT/pos/venta-ux
JSON Entrada
Body
{
"facturaNro": 123456789,
"monto": 50000,
"cuotas": 12,
"plan": 1
}
Donde:
facturaNro: int(12) Corresponde al número de factura generado por el sistema.
monto: int(12) Monto inicial de venta.
cuotas: int(4) Cantidad de cuotas para el pago.
Valor 0 para ventas en un solo pago.
Valor mayor a 1 para ventas en cuotas (con valor 1 retornaría un error).
plan: int(4) Plan de pago para promociones o descuentos:
Valor 1 para pago en cuotas (cuando las cuotas son mayores a 1).
Valor 0 para ventas en un solo pago.
Success HTTP/1.1 200 OK
Response
Body
{
"bin": "9999999999",
"nsu": "999999"
}
Donde:
bin: string(10) Corresponde al número BIN de la tarjeta asociada a la operación. Se puede utilizar este valor para realizar
descuentos según el tipo de tarjeta.
nsu: string(6) Código de operación interna del POS. Este número debe ser enviado junto con el monto en el servicio de En
vío de monto.
Una vez recibido los datos del Servicio se envía el monto a cobrar y el nsu al servicio de Envío de monto
Error Status 500: Error interno del POS
Response
Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra
Body
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
Solicitud Venta Forzado Débito
Esta opción se utiliza para forzar que la operación sea con una tarjeta de débito, por lo tanto si se utiliza este endpoint dará un error al
pasar una tarjeta de crédito.
Método POST
URL IP:PORT/pos/venta/debito
JSON Entrada
Body
{
"facturaNro": 123456789
}
Donde:
facturaNro: int(12) Corresponde al número de factura generado por el sistema.
Success HTTP/1.1 200 OK
Response
Body
{
"bin": "9999999999",
"nsu": "999999"
}
Donde:
bin: string(10) Corresponde al número BIN de la tarjeta asociada a la operación. Se puede utilizar este valor para realizar
descuentos según el tipo de tarjeta.
nsu: string(6) Código de operación interna del POS. Este número debe ser enviado junto con el monto en el servicio de En
vío de monto.
Una vez recibido los datos del Servicio se envía el monto a cobrar y el nsu al servicio de Envío de monto
Error Status 500: Error interno del POS
Response
Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra
Body
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
Solicitud Venta Forzado Crédito
Esta opción se utiliza para forzar que la operación sea con una tarjeta de crédito, por lo tanto si se utiliza este endpoint dará un error
al pasar una tarjeta de débito
Método POST
URL IP:PORT/pos/venta/credito
JSON Entrada
Body
{
"facturaNro": 123456789,
"cuotas": 12,
"plan": 1
}
Donde:
facturaNro: int(12) Corresponde al número de factura generado por el sistema.
cuotas: int(4) Cantidad de cuotas para el pago.
Valor 0 para ventas en un solo pago.
Valor mayor a 1 para ventas en cuotas (con valor 1 retornaría un error).
plan: int(4) Plan de pago para promociones o descuentos:
Valor 1 para pago en cuotas.
Valor 0 para ventas en un solo pago.
Success HTTP/1.1 200 OK
Response
Body
{
"bin": "9999999999",
"nsu": "999999"
}
Donde:
bin: string(10) Corresponde al número BIN de la tarjeta asociada a la operación. Se puede utilizar este valor para realizar
descuentos según el tipo de tarjeta.
nsu: string(6) Código de operación interna del POS. Este número debe ser enviado junto con el monto en el servicio de En
vío de monto.
Una vez recibido los datos del Servicio se envía el monto a cobrar y el nsu al servicio de Envío de monto
Error Status 500: Error interno del POS
Response
Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra
Body
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
Envío de Monto
Método POST
URL IP:PORT/pos/descuento
JSON Entrada {
"bin": "9999999999",
"nsu": "999999",
"monto": 150000
}
Donde:
bin: string(10) Es el número BIN que fue respuesta del Paso 1.
nsu: string(6) Código de la operación que fue respuesta del Paso 1.
monto: int(12) Es el valor de descuento o monto de la transacción.
Success HTTP/1.1 200 OK
Response
Body
{
"codigoAutorizacion": "575849",
"nroBoleta": "000270613845",
"codigoComercio": "5051107",
"nombreTarjeta": "VISA - PREPAGA - BANCO ITAU PY",
"pan": "1234",
"mensajeDisplay": "APROBADA",
"saldo": 150000,
"nombreCliente": "GONZALEZ/JOSE",
"issuerId": "VS"
"montoVuelto": 30000,
}
Donde:
codigoAutorizacion: string(6) Es el código de autorización generado por el POS.
nroBoleta: string(12) Corresponde al número de ticket.
codigoComercio: string(12) Identificador del comercio generado por el POS.
nombreTarjeta: string(40) Identificador de la tarjeta.
pan: string(4) Personal Account Number. Son los últimos 4 dígitos de la tarjeta.
mensajeDisplay: string(40) Mensaje enviado por el POS según el estado de la transacción.
saldo: int(12) Se envía cuando son tarjetas de débito que tienen saldo en cuenta.
nombreCliente: string(26) Nombre de la persona registrada en la tarjeta.
issuerId: string(2) Identificador del tipo de tarjeta utilizado.
montoVuelto: integer(12) Monto del vuelto ingresado en el POS.
Algunos campos pueden no aparecer, dependiendo del tipo de tarjeta utilizada, ningún campo puede ser
utilizado como requerido por el sistema.
Error Status 500: Error interno en el POS
Response
Status 400: Transacción cancelada, transacción rechaza, pin inválido o error de validación
{
"statusCode": 400,
"error": "Bad Request",
"message": "Mensaje enviado por el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
Verificación de conexión de POS - Mensaje ECO
Método POST
URL IP:PORT/pos/eco
JSON Entrada {
"eco": 1,
}
Donde:
eco: int(2) Corresponde a un número de hasta dos dígitos a ser enviado al POS.
Success Response HTTP/1.1 200 OK
{
"eco": 1,
}
Donde:
eco: int(2) El POS retorna el mismo número enviado inicialmente
Error Response Status 500: Error interno del POS
Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
Status 400: Error de rango. El número proporcionado supera el rango permitido, de 0 a 99
{
"statusCode": 400,
"error": "Bad Request",
"message": "Error de rango: 299"
}
TABLA DE ISSUER ID's
Marca Tipo IssuerID
AMERICAN EXPRESS Crédito AC
BANCARD Crédito BC
CABAL Crédito CB
CREDIFIELCO Crédito CC
CARTA CLAVE Crédito CL
PANAL Crédito CP
DINERS CLUB Crédito DC
CREDICARD Débito IC
INFONET Débito ID
MASTERCARD Crédito MC
MASTERCARD Débito MD
CREDICARD Crédito PC
UNICA Débito UD
CREDICARD Débito UD
VISA Crédito VC
VISA Débito VD
VISA LOCAL Crédito VS
TARJETA DEBITO Débito TD
TARJETA CREDITO Crédito TC