View Categories

Comunicación y mensajes.

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\",\"key\":\"<KEY>\",\"cookie\":\"<COOKIE>\",\"sandbox\":\"false\"}\n"
//Ejemplo de cadena de texto para consulta de estatus de una transacción enfocado a cuando se tiene token

"{\"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.

CampoTipo de datoDescripciónTiposRequerido
actionTypeStringDefine el tipo de acción que se llevará a cabo en Pagando Check Pad²OPERATIVE, LOG_IN, GET_TRANSACTION_STATUSSí
operationTypeStringDefine el tipo de operación a realizar por la Pagando Check Pad²SALE, REFUND, CHECK_IN, CHECK_OUT, CANCELSí, si actionType es OPERATIVE
amountStringMonto de la operación. Debe estar en formato "0.00" con comillas y dos decimales—Sí, si actionType es OPERATIVE
folioStringFolio de la transacción relacionada. Corresponde a la transacción originalEj: PAG-00000001Sí, si operationType es CHECK_OUT, REFUND o CANCEL
commerceReferenceStringReferencia interna del negocio para control de transacciones—Sí
cookieStringCookie provisto por el equipo de Pagando¹—Sí, si actionType es LOG_IN
keyParamStringKey provista por el equipo de Pagando¹—Sí, si actionType es LOG_IN
sandBoxBooleanIdentifica si la operación se realiza en entorno de pruebastrue, falseNo
tokenStringToken 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 (POR TOKEN DE IDEMPOTENCIA)

{
	"actionType":"GET_TRANSACTION_STATUS", 
	"token":"08e54c57f2741dc07d572a990ba3ba25eea10c05f8a862cc10f7903d9b6d332159"
}

GET TRANSACTION STATUS (POR REFERENCIA EXTERNA)

{
	"actionType":"GET_TRANSACTION_STATUS", 
	"externalReference":"<TU_REFERENCIA>"
}

Nota: Para consultar mediante referencia externa, el valor del campo “externalReference” debe ser generado por el negocio previamente al momento realizar una operativa y enviado mediante el campo commerceReference.

Json de obtener último mensaje (Ejemplo)

 {
 	 "actionType":"GET_LAST_MESSAGE"       
 }

Json de cancelar proceso (Ejemplo)

{
	"actionType":"CANCEL_PROCESS"
}

Ejemplos de JSON (Respuestas).

Glosario de campos

Respuesta Genérica

CampoTIpo de datoDescripción
codeStringCódigo definido de comunicación
messageStringMensaje de comunicación

Respuesta exitosa

CampoTIpo de datoDescripción
accountTypeStringTipo cuenta que se utilizó (DEBITO, CREDITO)
aidStringAID perteneciente a tarjeta
amountStringMontó total de la transacción
arqcStringCriptograma único
authCodeStringNúmero de identificación del emisor
cardBrandStringMarca de tarjeta
currencyStringMoneda en la que se realizó la compra
descriptionMessageStringMensaje descriptivo de el servidor
employeeStringEmpleado
emvTypeStringTipo de lectura de tarjeta
folioStringFolio de la transacción
idempotencyTokenStringId de identificación de transacción
last4StringUltimos 4 dígitos de tajeta
operationTypeStringTipo de operación realizada
requireSignatureStringLa firma fue requerida para autorizar la transacción
responseCodeStringCódigo de respuesta
terminalSerialNumberStringNúmero de serie de la terminal
transactionTimeStringMomento de la transacción
statusStringEl estado actual de la transacción consultada
tipAmountStringEl 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) 

{
  "accountType": "DEBIT",
  "aid": "A0000000031010",
  "amount": 99.0,
  "arqc": "696B2CA42338A4F4",
  "authCode": "A45186",
  "cardBrand": "VISA",
  "currency": "MXN",
  "descriptionMessage": "Successful approval/completion or that VIP PIN verification is valid",
  "employee": "",
  "emvType": "CONTACTLESS",
  "folio": "PAG-000000030093",
  "idempotencyToken": "",
  "last4": "4246",
  "operationType": "SELL",
  "requireSignature": "NOT_REQUIRED",
  "responseCode": 0,
  "status": "APPROVED",
  "terminalSerialNumber": "",
  "tipAmount": "0.00",
  "transactionTime": "1764799291087"
}
Suscribirse
Notificar de
guest
0 Comentarios
Más antiguo
Más reciente Más votado
Comentarios en línea
Ver todos los comentarios
Ingresar
Crear cuenta