Recibiendo la respuesta

Para cada operación de venta, reimpresión o cancelación la terminal enviará la respuesta en formato JSON a un servicio para que pueda ser procesada. Dicho servicio puede ser local en la intranet, o estar expuesto públicamente en internet mediante una url o ip. A continuación se detallan los requisitos para que puedas desarrollar dicho servicio.

Cosas a tener en cuenta

Se puede emplear cualquier lenguaje de programación que se desee y permita crear una API REST.
El servicio debe estar funcionando siempre que se requiera realizar cobros con la terminal ya que es ahí donde se enviará la respuesta de la operación.
La terminal debe poder alcanzar el servicio en todo momento para poder realizar el flujo completo de una transacción.
En caso de que la terminal indique que no puede enviar la respuesta al servicio, se debe verificar inmediatamente si el servicio está funcionando correctamente para poder realizar el flujo correcto de una transacción.

Requisitos

Al ser consumido el servicio, debe regresar un HTTP Status Code 20*.
El verbo HTTP devuelto debe ser POST.
Al consumir la terminal el servicio, debe venir en el body de la respuesta el siguiente JSON, con especial atención al parámetro code el cuál debe ser 00.

{
    "code": "00",
    "message": "Recibido"
}

El mensaje dentro del parámetro message puede contener cualquier texto.

Modelo de datos

Cuando se realiza una venta, reimpresión o cancelación se envía en formato JSON la respuesta de la operación al servicio de respuesta con un modelo de datos como sigue:

{
  "affiliation": "string",
  "aid": "string",
  "amount": "string",
  "applicationLabel": "string",
  "arqc": "string",
  "authCode": "string",
  "bankName": "string",
  "cardExpDate": "string",
  "cardNumber": "string",
  "cardType": "string",
  "cardTypeName": "string",
  "cityName": "string",
  "customerName": "string",
  "folioNumber": "string",
  "hasPin": boolean,
  "hexSign": "string",
  "internalNumber": "string",
  "isQps": decimal,
  "message": "string",
  "moduleCharge": "string",
  "moduleLote": "string",
  "orderId": "string",
  "preAuth": "string",
  "preStatus": decimal,
  "promotion": "string",
  "rePrintDate": "string",
  "rePrintMark": "string",
  "reprintModule": "string",
  "responseCode": "string",
  "storeName": "string",
  "streetName": "string",
  "tableId": "string",
  "terminalId": "string",
  "ticketDate": "string",
  "tipAmount": "string",
  "tipLessAmount": "string",
  "traceability": object,
  "transDate": "string",
  "transType": "string",
  "transactionCertificate": "string"
}

Dependiendo de la operación realizada y del tipo de tarjeta leída por la terminal, algunos valores pueden o no viajar en la respuesta. A continuación se detalla cada valor de la respuesta:

affiliation [String, opcional]: Número de afiliación del comercio
aid [String, opcional]: Información sobre la lectura de la tarjeta.
amount [String, opcional]: Monto total de la transacción con todo y propina.
applicationLabel [String, opcional]: Información sobre la lectura de la tarjeta.
arqc [String, opcional]: Información sobre la lectura de la tarjeta.
authCode [String, opcional]: Valor generado por la autoridad de autorización para una transacción aprobada.
bankName [String, opcional]: Nombre de la institución financiera emisora de la tarjeta.
cardExpDate [String, opcional]: Fecha de expiración de la tarjeta en formato MM/YY.
cardNumber [String, opcional]: Últimos 4 dígitos de la tarjeta leída.
cardType [String, opcional]: Identificador de tipo de tarjeta. Débito (D), crédido (C).
cardTypeName [String, opcional]: Representa el nombre del tipo de marca de la tarjeta, Visa, Master Card, etc.
cityName [String, opcional]: Ciudad con la que se dió de alta el comercio.
customerName [String, opcional]: Nombre del tarjetahabiente.
folioNumber [String, opcional]: Número identificador de transacción que puede ser enviado en la solicitud de venta.
hasPin [Boolean, opcional]: Indica si la transacción fue aprobada mediante NIP.
hexSign [String, opcional]: Firma autógrafa en caso de no contar con NIP la tarjeta.
internalNumber [String, opcional]: Identificador interno.
isQps [Decimal, opcional]: Indica el monto cobrado por quick payment service.
message [String, opcional]: Mensaje que indica el estatus de la transacción. Puede indicar si esta fue aceptada o declinada y por qué motivo.
moduleCharge [String, opcional]: Identificador interno.
moduleLote [String, opcional]: Identificador interno.
orderId [String, opcional]: Identificador de número de transacción. Puede ser utilizado posteriormente en reimpresión y cancelación.
preAuth [String, opcional]: Pre-autorización.
preStatus [Decimal, opcional]: Pre-autorización.
promotion [String, opcional]: Indica el número de meses sin intereses en que una transacción fue parcializada.
rePrintDate [String, opcional]: Indica la versión de la aplicación.
rePrintMark [String, opcional]: Identificador interno.
reprintModule [String, opcional]: Identificador interno.
responseCode [String, opcional]: Código de respuesta en función del estatus de la transacción. El valor 00 representa una transacción exitosa, cualquier otro valor se puede tomar como un problema con la transacción.
storeName [String, opcional]: Nombre del comercio dado de alta.
streetName [String, opcional]: Dirección del comercio dado de alta.
tableId [String, opcional]: Identificador de número de mesa.
terminalId [String, opcional]: Número de serie de la terminal.
ticketDate [String, opcional]: Fecha y hora de la transacción.
tipAmount [String, opcional]: Indica el monto para propina, en caso de ser enviado.
tipLessAmount [String, opcional]: Indica el monto menos propina.
traceability [Object, opcional]: Objeto para envío de información adicional.
transDate [String, opcional]: Fecha y hora de la transacción.
transType [String, opcional]: Indica el tipo de operación realizada. Venta (A), Cancelación (V).
transactionCertificate [String, opcional]: Información sobre la lectura de la tarjeta.

Objeto traceability

Dentro del objeto traceability, se puede agregar información adicional en formato JSON en caso de requerirse, dicha información será devuelta en la respuesta de la terminal hacia el servicio.

Ejemplo:

{
    "traceability": {
      "idProducto": "123456",
      "idTienda": 0987
    }
}

Respuestas

Transacción éxitosa

Este es un ejemplo de una transacción exitosa sin NIP.

{
  "affiliation": "7110001",
  "applicationLabel": "MASTERCARD",
  "arqc": "9A011111A8C81111",
  "aid": "A0000000041010",
  "amount": "100.49",
  "authCode": "222222",
  "bankName": "INBURSA",
  "cardExpDate": "01/23",
  "cardType": "C",
  "cardTypeName": "MASTERCARD",
  "cityName": "Monterrey NUEVO LEON",
  "responseCode": "00",
  "hasPin": false,
  "hexSign": "00000100000001DA0000009E000000040800031CFF0FF02",
  "isQps": 0.0,
  "message": "Transacción exitosa",
  "moduleCharge": "1",
  "moduleLote": "1",
  "customerName": "John Doe",
  "terminalId": "0800000000",
  "orderId": "200310000001-0800000000",
  "preAuth": "0",
  "preStatus": 0.0,
  "promotion": "0",
  "rePrintDate": "1.1.8_20200220",
  "rePrintMark": "MASTER",
  "reprintModule": "C",
  "cardNumber": "0001",
  "storeName": "Netpay",
  "streetName": "Ricardo Maragain",
  "ticketDate": "MAR. 19, 20 12:51:45 ",
  "tipAmount": "0.0",
  "tipLessAmount": "1.0",
  "transDate": "2020-03-19 12:51:56.CST",
  "transType": "A",
  "transactionCertificate": "D021DCDC1AE1C11F",
  "traceability": {}
}

Configuración de la aplicación

Al momento de guardar por primera vez la url del servicio de respuesta dentro de la configuración de la app, la terminal enviará el siguiente JSON hacia el servicio:

{
  "folioNumber": "",
  "hasPin": false,
  "internalNumber": "",
  "isQps": 0.0,
  "preStatus": 0.0,
  "tableId": ""
}

Si el servicio responde correctamente, aparecerá el siguiente mensaje en la terminal

Datos guardados con éxito tpv Smart

Cancelado por el Usuario / time out

En caso de enviar una solicitud a la terminal y esta sea cancelada desde la terminal o el tiempo de espera que es al rededor de 1 minuto se agote, se enviará el siguiente mensaje en formato JSON hacia el servicio de respuesta:

{
  "responseCode": "02",
  "hasPin": false,
  "internalNumber": "",
  "isQps": 0.0,
  "message": "Cancelado por el Usuario",
  "preStatus": 0.0,
  "tableId": "",
  "traceability": {}
}

Promoción inválida para tipo de tarjeta

En caso de utilizar una tarjeta para cierto tipo de promoción, como por ejemplo meses sin intereses, y esta no soporte dicha promoción (por ejemplo una tarjeta de débito), se recibirá el siguiente mensaje en formato JSON:

{
  "responseCode": "48",
  "hasPin": false,
  "internalNumber": "",
  "isQps": 0.0,
  "message": "PROMOCION NO VALIDA PARA EL TIPO DE TARJETA",
  "preStatus": 0.0,
  "tableId": "",
  "traceability": {}
}

Otro tipo de respuestas

Como se mencionó más arriba, se pueden obtener diferentes tipos de respuesta según el banco emisor de la tarjeta. Un responseCode diferente de 00 indica que la transacción no fue exitosa y podemos ver el motivo en el message.

{
  "responseCode": "13",
  "hasPin": false,
  "internalNumber": "",
  "isQps": 0.0,
  "message": "TRANSACCION NO PERMITIDA",
  "preStatus": 0.0,
  "tableId": "",
  "traceability": {}
}

{
  "responseCode": "56",
  "hasPin": false,
  "internalNumber": "",
  "isQps": 0.0,
  "message": "TARJETA INVALIDA",
  "preStatus": 0.0,
  "tableId": "",
  "traceability": {}
}


{
  "responseCode": "14",
  "hasPin": false,
  "internalNumber": "",
  "isQps": 0.0,
  "message": "TARJETA INVALIDA",
  "preStatus": 0.0,
  "tableId": "",
  "traceability": {}
}

Recursos Checkout

Recursos terminal Smart