Integración de API en la nube

Con una integración en la nube, tu software de POS y el terminal de pago se comunican entre sí a través de Internet, sin necesidad de cable físico ni conexión local.

Cómo funciona (a alto nivel):

1. El software de POS envía una solicitud de pago a la plataforma Market Pay.

2. La plataforma Market Pay reenvía esta solicitud al terminal de pago.

3. El terminal gestiona la interacción con el cliente y procesa el pago.

4. El resultado se envía de vuelta a través de la plataforma.

5. Tu software de POS recibe el estado final de la transacción.

Este enfoque hace que la configuración sea más simple, flexible y fácil de escalar en múltiples dispositivos.

Configuración de comunicación segura

Antes de que tu ECR pueda intercambiar mensajes con el terminal de pago, debe estar instalado un certificado seguro:

1. Debes crear una Solicitud de Firma de Certificado (CSR) y enviarla a Market Pay (tu gestor de implementación)

2. El equipo de AppOps de Market Pay emite el certificado y te lo devuelve.

3. Instalas el certificado en tu sistema.

👉 Lee la guía paso a paso para la configuración del certificado

Configura tu red

Asegúrate de que tu red y firewall permitan tráfico HTTPS saliente a los servicios de Market Pay y puntos finales de socios. Añade a la lista blanca las IP y puertos TCP a continuación para que las aplicaciones POS y los terminales puedan acceder a los servicios que necesitan.

• NTMS – Sistema de Gestión de Terminales: Gestiona configuraciones y actualizaciones.

• MPG – Pasarela Market Pay: Procesa y enruta todas las transacciones.

• RKI – Inyección Remota de Claves: Gestiona claves de cifrado de forma remota.

👉 Consulta la lista completa de requisitos de configuración de red

Comunicación POS ↔ Terminal

Tu ECR se comunica con el terminal usando los siguientes endpoints de la API:

Aquí encontrarás las especificaciones detalladas: api-hub.market-pay.com

1. POST /process-transaction

• Qué hace: Inicia un nuevo pago y muestra la pantalla de pago en el terminal.

• Cómo funciona: Las actualizaciones de estado (tarjeta insertada, PIN introducido, pago autorizado) se envían a tu URL de notificación configurada.

• Cuándo usarlo: Cada vez que un cajero inicia un pago.

👉 Consulta la documentación detallada para /process-transaction

2. GET /last-transaction

• Qué hace: Recupera el resultado de la transacción más reciente.

• Cómo funciona: Ayuda a recuperar resultados si el POS perdió la conexión. Revisa siempre el transactionId para asegurarte de que coincides con la solicitud correcta.

• Cuándo usarlo: Si tu POS no recibió un resultado y necesitas confirmar qué ocurrió.

👉 Consulta la documentación detallada para /last-transaction

3. POST /cancel-transaction/{terminal-id}

Qué hace:
Cancela un pago previamente exitoso realizando una reversión de transacción.

Cómo funciona:
El terminal envía una solicitud de reversión al adquirente. Las actualizaciones de estado (iniciada, en progreso, completada) se envían a tu URL de notificación.

Cuándo usarlo:
Úsalo cuando se haya realizado un pago por error o necesite ser anulado antes de la liquidación.

👉 Consulta la documentación detallada para /cancel-transaction

4. POST /update-terminal

• Qué hace: Solicita al terminal que actualice su software o configuración.

• Cuándo usarlo: Durante despliegues, mantenimiento o antes de introducir nuevas funciones.

👉 Consulta la documentación detallada para /update-terminal

5. POST /abort-transaction

• Qué hace: Cancela una transacción en curso.

• Cómo funciona: Si la solicitud llega temprano, la transacción se detiene. Si llega demasiado tarde, el terminal puede completarla de todos modos; en ese caso, el POS debe enviar un Reembolso.

• Cuándo usarlo: Si un cliente o cajero decide cancelar antes de la finalización.

👉 Consulta la documentación detallada para /abort-transaction

6. GET /terminals

• Qué hace: Lista todos los terminales conectados para un código de tienda dado.

• Cómo funciona: Devuelve una respuesta vacía si no hay sesiones activas.

• Cuándo usarlo: Al iniciar el POS, para comprobar qué terminales están disponibles.

👉 Consulta la documentación detallada para /get-terminals

7. Cómo generar tu CSR (Solicitud de Firma de Certificado)

Para obtener tu certificado, necesitas generar un CSR (Solicitud de Firma de Certificado) y una clave privada usando OpenSSL.

1. Genera el CSR y la clave privada

Usa el siguiente comando según tu entorno:

Para pre-producción:

openssl req -nodes -newkey rsa:2048 -keyout POS_MerchantName_PREPROD_PRIVATEKEY.key -out POS_MerchantName_PREPROD_CSR.csr

Para producción:

openssl req -nodes -newkey rsa:2048 -keyout POS_MerchantName_PROD_PRIVATEKEY.key -out POS_MerchantName_PROD_CSR.csr

Reemplaza MerchantName con tu identificador real de comercio (por ejemplo, POS_MyShop_PREPROD_PRIVATEKEY.key).

2. Rellena la información requerida

Cuando el comando de OpenSSL te lo solicite, rellena los siguientes campos:

⚠️ Por favor, asegúrate de que el campo Organizational Unit (OU) indique claramente el uso del certificado; esta información es obligatoria.

Los demás campos pueden dejarse vacíos.

3. Envía el archivo CSR

Una vez generado el CSR, envía el archivo .csr a tu contacto de Market Pay.
No envíes el archivo .key; consérvalo guardado de forma segura.

4. Opcional (solo para pruebas)

También puedes generar un CSR usando una herramienta en línea (no recomendado para producción):
👉 Generador en línea de CSR y clave – SSL.com