INTEGRACIÓN

POS CAJA

Especificaciones Técnicas
Histórico de Cambios
Versión Fecha Modificado por Descripción

1.0 29/10/2021 Versión inicial.

1.1 11/11/2021 Miguel Alarcon Sugerencias de Bepsa

2
Índice
Introducción ........................................................................................................................................................... 4
Arquitectura............................................................................................................................................................ 4
Conceptos generales ............................................................................................................................................ 5
Datos fijos..................................................................................................................................................... 5
Mensajes ................................................................................................................................................................... 5
createPayment .......................................................................................................................................... 5
Ejemplo – createPayment (request) ............................................................................................ 6
Ejemplo – createPayment (response) ......................................................................................... 6
queryPayment ........................................................................................................................................... 6
Ejemplo – queryPayment (request)............................................................................................. 7
Ejemplo – queryPayment (response) ......................................................................................... 7
cancelPayment ......................................................................................................................................... 8
Ejemplo – cancelPayment (request)............................................................................................ 8
Ejemplo – cancelPayment (response)......................................................................................... 9
Estructuras Adicionales .................................................................................................................................. 10
RequestBody (REST JSON) ................................................................................................................. 10
ResponseBody (REST JSON) .............................................................................................................. 11
Diagrama de Secuencia ..................................................................................................................................... 12

3
 Introducción

El presente documento tiene como fin especificar la mensajería para integración

desde sistema externos con los diferentes componentes de la solución Bepsa implementada
por GEOCOM. Estas especificaciones pueden sufrir cambios ya que se encuentran en
desarrollo.

Arquitectura

4
Conceptos Generales
Datos fijos

El intercambio de mensajes se realizará mediante una conexión HTTP utilizando JSON.

Mensajes
Los mensajes soportados por el componente son:

• createPayment.
• queryPayment.
• cancelPayment

createPayment

Nombre createPayment
Método Http POST
URL https://{IPServicio}:{Puerto}/cashierSystemServices/payments/createPayment
Descripción Se invoca para iniciar una venta utilizando el pos.

Campos Requerimiento (formato JSON)

Nombre Obl Tipo Descripción
requestBody Si Body Ver estructura RequestBody

Nombre Obl Tipo Descripción

responseBody Si Body Ver estructura RequestBody

5
Ejemplo – createPayment (request)
{
"terminalId": "9990",
"commerceId": "99",
"localId": "90",
"amount": 1500,
"currency": "600",
"dateTime": "2021-10-29T20:24:21.363Z",
"externalSystemReference": "20191004102000"
}
Ejemplo – createPayment (response)
{
"internalReferenceValue": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"authorizationCode": "5881100",
"merchantCode": "99",
"terminalCode": "9990",
"amount": 1200,
"hostMessage": "PAYMENT CREATED",
"internalDescription": "CREATEPAYMENT",
"status": "CREATED",
}
queryPayment

Nombre queryPayment
Método Http POST
URL https://{IPServicio}:{Puerto}/cashierSystemServices/payments/queryPayment
Descripción Se invoca para consultar el estado de una transacción.
Se puede invocar varias veces de manera automática hasta tener el resultado
adecuado.

Campos Requerimiento (formato JSON)

Nombre Obl Tipo Descripción
requestBody Si Body Ver estructura RequestBody

Nombre Obl Tipo Descripción

responseBody Si Body Ver estructura RequestBody

Se debe enviar campo “externalSystemReference”, requestBody con el mismo valor que la

transacción de venta que se desea consultar.

6
Ejemplo – queryPayment (request)
{
"terminalId": "9990",
"commerceId": "99",
"localId": "90",
"amount": 1500,
"currency": "600",
"dateTime": "2021-10-29T20:24:21.363Z",
"externalSystemReference": "20191004102030"
}
Ejemplo – queryPayment (response)
{
"internalReferenceValue": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"authorizationCode": "5881100",
"merchantCode": "99",
"terminalCode": "9990",
"amount": 1500,
"ticket": "12345678012",
"rrn": "201112345678012",
"trace": "",
"batch": "",
"balance": 0,
"refundedAmount": 0,
"card": "",
"aquirerId": "",
"productId": "",
"paymentTypeId": "",
"operationType": "02",
"date": "2021-10-29T20:24:21.394Z",
"issuerId": "",
"installments": "01",
"hostMessage": "WAITING HOST RESPONSE",
"internalDescription": "QUERYPAYMENT",
"internalCode": "40",
"authorizorCode": "",
"authorizorDescription": "string",
"currency": "600",
"status": "INPROCESS",
“mensajeCliente”:”Felicidades gano 100.000 gs”,
"externalSystemReference": "20191004102030"
}

7
cancelPayment

Nombre cancelPayment
Método Http POST
URL https://{IPServicio}:{Puerto}/cashierSystemServices/payments/cancelPayment
Descripción Se invoca para cancelar una transacción.

Campos Requerimiento (formato JSON)

Nombre Obl Tipo Descripción

requestBody Si Body Ver estructura RequestBody

Nombre Obl Tipo Descripción

responseBody Si Body Ver estructura RequestBody

Se debe enviar campo “externalSystemReference”, requestBody con el mismo valor que la

transacción de venta que se desea cancelar.

Ejemplo – cancelPayment (request)

{
"terminalId": "9990",
"commerceId": "99",
"localId": "90",
"amount": 1000,
"currency": "600",
"dateTime": "2021-10-29T20:24:21.363Z",
"externalSystemReference": "20191004102050"
}

8
Ejemplo – cancelPayment (response)
{
"internalReferenceValue": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"authorizationCode": "5881100",
"merchantCode": "99",
"terminalCode": "9990",
"amount": 1000,
"ticket": "A215",
"rrn": "89200",
"trace": "",
"batch": "",
"balance": 0,
"refundedAmount": 0,
"card": "",
"aquirerId": "",
"productId": "",
"paymentTypeId": "",
"operationType": "02",
"date": "2021-10-29T20:24:21.394Z",
"issuerId": "",
"installments": "01",
"hostMessage": "PAYMENT CANCELED",
"internalDescription": "CANCELPAYMENT",
"internalCode": "50",
"authorizorCode": "",
"authorizorDescription": "string",
"currency": "600",
"status": "PROCESSED",
"externalSystemReference": "20191004102050"
}

9
Estructuras Adicionales
En los JSON de los servicios se encuentran algunas estructuras, detalladas a continuación.

RequestBody (REST JSON)

Nombre requestBody
Descripción Datos de identificación y auditoría del mensaje

Campos (formato JSON)

Nombre Obl Tipo Descripción

dateTime Si Texto Fecha de envió de la solicitud (invocación).

Formato:
• aaaa-mm-dd hh:mm:ss
Hora (hh) del 00 al 23
amount Si Número Monto de la transacción.
localId Si Texto Identificador del local desde el cual se genera la
transacción en el sistema del cliente

terminalId Si Texto Identificador de la terminal en el sistema del

cliente.
commerceId Si Texto Identificador del comercio desde el cual se genera
la transacción.
currency Si Texto Moneda de uso en la transacción.
externalSystemReference Si Texto Identificador externo unico

10
ResponseBody (REST JSON)

Nombre responseBody
Descripción Datos básicos de respuesta

Campos (formato JSON)

Nombre Obl Tipo Descripción
externalSystemReference Si Texto Identificador externo único.
internalReferenceValue Si Texto Identificador interno
authorizationCode No Texto Código de autorización
merchantCode No Texto Código de comercio
terminalCode No Texto Identificador de la terminal en el sistema del cliente.
amount No Numero Monto de la transacción
ticket No Texto Identificador de ticket
rrn No Texto Identificador de recuperación de la transacción
trace No Texto Identificador de trazabilidad.
batch No Texto Identificador de lote
balance No Numero Saldo disponible
refundedAmount No Numero Monto de devolución
additionalAmount No Numero Monto adicional, propina
Card No Texto Número de tarjeta
aquirerId No Texto Identificador de adquirente
productId No Texto Identificador de producto
paymentTypeId No Texto Identificador de tipo de pago
operationType No Texto Identificador de tipo de operacion
Date No Texto Fecha de envió de la solicitud (invocación).
Formato:
• aaaa-mm-dd hh:mm:ss
Hora (hh) del 00 al 23
issuerId No Texto Identificador de emisor
installments No Texto Pagos
hostMessage No Texto Mensaje del servicio
internalDescription No Texto Descripción interna
internalCode No Texto Código interno
authorizorCode No Texto Codigo de autorizador
authorizorDescription No Texto Descripción de autorizador
currency No Texto Moneda de la transaccion
Status No Texto Estado de la transaccion

11
Diagrama de Secuencia

12