Aspectos generales
Como parte del proceso y para asegurar la recepción de mensajes tomar en cuenta lo siguiente.
- Al ser una comunicación TCP/IP no tenemos un tiempo de espera predeterminado (normalmente no es más de un segundo), por lo que el cliente tendrá que generar una lógica para la recepción de mensajes en espera de una transacción.
- El cliente deberá de implementar una mecánica de verificación de estatus de operación después de esperar durante 120 segundos la transacción, por medio del uso de tipo de operación GET_TRANSACTION_STATUS.
- El cliente tendrá que tener validado la recepción de una sola respuesta del socket por transacción enviada.
- Toda comunicación es por medio de JSON.
Estructura del JSON
Como antes mencionado la comunicación entre dispositivos se realiza por medio de JSON, por lo que se tiene que tomar en cuenta las siguientes cuestiones:
- El JSON debe presentar una estructura completa y válida, conformando un objeto o un arreglo de objetos bien definido.
- Todas las claves (nombres de propiedades) dentro del JSON deben ir obligatoriamente entre comillas dobles.
- Las estructuras de datos internas deben adherirse estrictamente a los estándares de formato JSON.
- El JSON debe ser transmitido como una cadena de texto, asegurando que se respeten y manejen correctamente los caracteres de escape necesarios.
- La cadena de texto del JSON debe incluir un salto de línea al final (\n) para indicar el término del mensaje.
- Estos criterios aplican para la recepción y envió de mensajes.
//Ejemplo de cadena de texto para una venta.
"{\\"actionType\\":\\"OPERATIVE\\",\\"operationType\\":\\"SALE\\",\\"amount\\":\\"252.00\\",\\"folio\\":\\"\\",\\"commerceReference\\":\\"\\",\\"id\\":\\"\\",\\"cvvAmex\\":\\"\\"}\\n"
//Ejemplo de cadena de texto para log in
"{\\"operationType\\":\\"LOG_IN\\",\\"keyParam\\":\\"<KEY>\\",\\"cookie\\":\\"<COOKIE>\\",\\"sandbox\\":\\"false\\"}\\"
//Ejemplo de cadena de texto para consulta de estatus de una transacción
"{\\"actionType\\":\\"GET_TRANSACTION_STATUS\\",\\"token\\":\\"08e44c57f2741dc07d572a990ba3ba25eea10c05f8a862cc10f7903d9b6d332159\\"}\\n"
Ejemplo para el envío de mensajes
Paso 1: Preparación del mensaje
De acuerdo con la especificación del servicio, el mensaje JSON debe generarse siguiendo su estructura definida. Recomendamos encarecidamente el uso de librerías para facilitar la manipulación del JSON durante el desarrollo.
String actionType = "LOG_IN";
String jsonRequest = "{\\"operationType\\": \\"" + actionType + "\\"}";
tipoDeAccion = "LOG_IN"
solicitudJson = "{" + "operationType: \\"" + tipoDeAccion + "\\"" + "}"
Paso 2: Enviar mensaje al socket
Para enviar el mensaje, utiliza librerías o herramientas de manejo de texto. Estas te permitirán transmitir el mensaje como un flujo de datos (stream) a través del socket previamente establecido.
PrintWriter out = new PrintWriter(socket.getOutputStream(), true);
out.println(jsonRequest);
canalDeSalida = NuevoCanalDeEscritura(socket.FlujoDeSalida)
ENVIAR(solicitudJson)
Ejemplo de recepción de mensajes
Paso 1: Generación de escucha continua.
Por la naturaleza del protocolo es necesario activar un mecanismo de escucha continua, ya que el procesamiento de las transacciones puede variar. debido a que la terminal tiene procesos internos que pueden variar el tiempo de respuesta, de está manera nos aseguramos de siempre recibir el resultado
try (BufferedReader in = new BufferedReader(new InputStreamReader(socket.getInputStream()))) {
String msg;
// se detiene en in.readLine() hasta recibir un mensaje terminado en '\\n'
while ((msg = in.readLine()) != null) {
messages.add(msg); // Añade el mensaje a una cola
}
}
UTILIZANDO canalDeEntrada = AbrirCanalDeLectura(socket.FlujoDeEntrada) HACER
MIENTRAS (hay_datos_para_leer_en(canalDeEntrada)) HACER
mensaje = LEER_LINEA(canalDeEntrada)
AÑADIR mensaje A cola_de_mensajes
FIN MIENTRAS
FIN UTILIZANDO
Para evitar la congestión del socket, recomendamos implementar una cola. Esta actúa como un búfer seguro, lo que permite que el hilo de red reciba mensajes rápidamente, mientras la lógica principal los procesa a su propio ritmo.
Paso 2: Procesamiento de mensaje
Una vez recibido el mensaje se deberá de procesar por medio de una herramienta que permita el convertir texto a un JSON para ser usado por el cliente. Es necesario recordar que el manejo de la respuesta recibida será según las necesidades del negocio.
String msg = messages.poll(); // Extrae un mensaje de la cola
if (msg != null) {
return msg;
}
mensaje = EXTRAER_DE_COLA(cola_de_mensajes)
SI mensaje NO ES NULO ENTONCES
DEVOLVER mensaje
FIN SI
Ejecución de Operación con PinPad.
Para realizar una operación desde la Pagando Check Pad se recomienda seguir el siguiente flujo:
Estructura de peticiones a la terminal
Como lo mencionado en el apartado de “Comunicación y mensajes” cada acción realizada a la terminal requiere una comunicación por medio de JSON. Para esto se establece la siguiente tabla que explica cada campo necesario para las operativas.
| Campo | Tipo de dato | Descripción | Tipos | Requerido |
|---|---|---|---|---|
actionType | String | Define el tipo de acción que se llevará a cabo en Pagando Check Pad | OPERATIVE, LOG_IN, GET_TRANSACTION_STATUS | Sí |
operationType | String | Define el tipo de operación a realizar por la Pagando Check Pad | SALE, REFUND, CHECK_IN, CHECK_OUT, CANCEL | Sí, si actionType es OPERATIVE |
amount | String | Monto de la operación. Debe estar en formato "0.00" con comillas y dos decimales | — | Sí, si actionType es OPERATIVE |
folio | String | Folio de la transacción relacionada. Corresponde a la transacción original | Ej: PAG-00000001 | Sí, si operationType es CHECK_OUT, REFUND o CANCEL |
commerceReference | String | Referencia interna del negocio para control de transacciones | — | Sí |
cookie | String | Cookie provisto por el equipo de Pagando | — | Sí, si actionType es LOG_IN |
keyParam | String | Key provista por el equipo de Pagando | — | Sí, si actionType es LOG_IN |
sandBox | Boolean | Identifica si la operación se realiza en entorno de pruebas | true, false | No |
token | String | Token proporcionado al realizar una venta, para verificar el estado de la transacción | — | Sí, si actionType es GET_TRANSACTION_STATUS |
Ejemplos de JSON (Envío).
Los ejemplos mostrados a continuación son para ejemplificar la estructura necesaria del json de una manera más amigable para el cliente, recodar que estos tiene que estar completamente en texto y con un saldo de línea al final de la cadena.
Ejemplos para JSON de configuración de terminal
{
"actionType":"LOG_IN",
"cookie":"cookie",
"keyParam":"key",
"sandbox":false,
}
Ejemplos de JSON para la realización de operativas
SALE
{
"actionType":"OPERATIVE", // Define la acción que se llevará acabo en la terminal
"operationType":"SALE", // Define el tipo de operación que se realizará
"amount":"255.00", // Monto el cual se cobrará
"folio":"",
"commerceReference":"Folio dado por el cliente"
}
CHECK_IN
{
"actionType":"OPERATIVE", // Define la acción que se llevará acabo en la terminal
"operationType":"CHECK_IN", // Define el tipo de operación que se realizará
"amount":"255.00", // Monto el cual se cobrará
"folio":"",
"commerceReference":"folio dado por el cliente"
}
CHECK_OUT
{
"actionType":"OPERATIVE",
"operationType":"CHECK_OUT",
"amount":"255.00",
"folio":"PAG-000000000123",
"commerceReference":"folio dado por el cliente"
}
CANCEL
{
"actionType":"OPERATIVE",
"operationType":"CANCEL",
"amount":"255.00",
"folio":"PAG-000000000123",
"commerceReference":"folio dado por el cliente"
}
REFUND
{
"actionType":"OPERATIVE",
"operationType":"REFUND",
"amount":"255.00",
"folio":"PAG-000000000123",
"commerceReference":"folio dado por el cliente"
}
GET TRANSACTION STATUS
{
"actionType":"GET_TRANSACTION_STATUS",
"token":"08e54c57f2741dc07d572a990ba3ba25eea10c05f8a862cc10f7903d9b6d332159"
}
Ejemplos de JSON (Respuestas).
Glosario de campos
Respuesta Genérica
| Campo | TIpo de dato | Descripción |
|---|---|---|
| code | String | Código definido de comunicación |
| message | String | Mensaje de comunicación |
Respuesta exitosa
| Campo | TIpo de dato | Descripción |
|---|---|---|
| accountType | String | Tipo cuenta que se utilizó (DEBITO, CREDITO) |
| aid | String | AID perteneciente a tarjeta |
| amount | String | Montó total de la transacción |
| arqc | String | Criptograma único |
| authCode | String | Número de identificación del emisor |
| cardBrand | String | Marca de tarjeta |
| currency | String | Moneda en la que se realizó la compra |
| descriptionMessage | String | Mensaje descriptivo de el servidor |
| employee | String | Empleado |
| emvType | String | Tipo de lectura de tarjeta |
| folio | String | Folio de la transacción |
| idempotencyToken | String | Id de identificación de transacción |
| last4 | String | Ultimos 4 dígitos de tajeta |
| operationType | String | Tipo de operación realizada |
| requireSignature | String | La firma fue requerida para autorizar la transacción |
| responseCode | String | Código de respuesta |
| terminalSerialNumber | String | Número de serie de la terminal |
| transactionTime | String | Momento de la transacción |
| BIN | String | Primeros 6 número de la tarjeta utilizada |
| BIN8 | String | Primeros 8 número de la tarjeta utilizada |
| merchantIdCode | String | Código de identificación |
| status | String | El estado actual de la transacción consultada |
| tipAmount | String | El monto cobrado de propina. |
Ejemplos de comunicación generica
{
"code": "0000",
"message": "mensaje de comunicación"
}
Ejemplo de respuesta de operación (Ejemplo)
{
"accountType":"DEBIT",
"aid":"A0000000000000",
"amount":0.0,
"arqc":"4F98EADSD4AEC141",
"authCode":"000000",
"cardBrand":"MASTERCARD",
"currency":"MXN",
"descriptionMessage":"Successful approval/completion or that VIP PIN verification is valid",
"employee":"",
"emvType":"CONTACTLESS",
"folio":"PAG-000000000000",
"idempotencyToken":"0000000000000000000000asda00000000dfeg000efadc000000000",
"last4":"0000",
"operationType":"SALE",
"requireSignature":"NOT_REQUIRED",
"responseCode":0,
"terminalSerialNumber":"",
"transactionTime":"0000000000000"
}
Ejemplo de respuesta de GET_STATUS_TRANSACTION (Ejemplo)
{
"AID": "A0000000041010",
"ARQC": "D6BC42132124A1E7",
"BIN": "557908",
"BIN8": "55790830",
"accountType": "DEBIT",
"amount": "253.0",
"authCode": "308840",
"brand": "MASTERCARD",
"description": "Successful approval/completion or that VIP PIN verification is valid",
"emvType": "CONTACTLESS",
"folio": "PAG-000000027399",
"last4": "5483",
"merchantIdCode": "2038173",
"operationType": "SELL",
"pinEntry": false,
"requireSignature": false,
"responseCode": "00",
"status": "APPROVED",
"tipAmount": "0.00",
"transactionTime": "2025-07-28T22:13:33.398Z"
}
![Bancos participantes](https://www.pagandocheck.com/wp-content/webpc-passthru.php?src=https://www.pagandocheck.com/wp-content/uploads/2021/09/bancos2.png&nocache=1")
