> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pay-me.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Requisitos y responsabilidades

> Requisitos y responsabilidades del comercio, el integrador, Pay-me PinPAD y Alignet.

## Matriz de responsabilidades

| Área | Comercio o integrador — sistema central | Pay-me PinPAD / Alignet | Validación conjunta |
| - | - | - | - |
| Red local | Alcanzar la IP y el puerto del terminal; configurar firewall y timeout. | Exponer el servidor HTTP en el Wiseasy P5L. | Ejecutar `GET /health` desde el sistema central. |
| Operación | Calcular el monto, generar y persistir `operationNumber` y aplicar la decisión de negocio. | Validar la solicitud; ejecutar el cobro, cancelación o extorno; y devolver el resultado. | Probar aprobación, rechazo, cancelación y recuperación por método; extorno únicamente CARD. |
| Idempotencia | Mantener una sola referencia por operación real y consultar ante incertidumbre. | Evitar un segundo cargo para la misma referencia y conservar el resultado. | Simular timeout, reenvío y consulta. |
| Concurrencia | Serializar solicitudes destinadas al mismo terminal. | Procesar una operación a la vez y devolver `409 POS_BUSY` a otra referencia. | Enviar solicitudes concurrentes controladas. |
| Configuración | Registrar IP, puerto y asociación entre sistema central, punto de atención y terminal. | Instalar la aplicación, configurar IP/puerto y verificar llaves. | Confirmar el estado operativo que muestra Pay-me PinPAD. |
| Seguridad | Proteger la red, los logs y los datos de conciliación. | No exponer datos sensibles de tarjeta en la respuesta. | Revisar evidencias sanitizadas. |
| Soporte | Conservar solicitudes, respuestas, códigos HTTP y marcas de tiempo. | Correlacionar la operación y apoyar el diagnóstico. | Definir responsables y escalamiento. |

## Requisitos del sistema central

### Cliente HTTP

* Implementa `GET /health`, `POST /authorize`, `GET /payments/{operationNumber}`, `POST /cancel`, `POST /reversals` y `GET /reversals/{operationNumber}`.
* Envía `Content-Type: application/json` en la autorización, la cancelación y el extorno.
* Configura al menos 100 a 110 segundos de timeout para `POST /authorize`, `POST /cancel` y `POST /reversals` con la espera de desarrollo actual.
* Abre una conexión por petición: todas las respuestas usan `Connection: close`; no reutilices keep-alive.
* Configura la consulta del cobro para cubrir aproximadamente 12–15 segundos, por ejemplo con timeout de 20 segundos.
* Lee el HTTP y el JSON; verifica `Cache-Control: no-store` y respeta `Retry-After: 2` en HTTP `202`.
* Maneja `200`, `202`, `400`, `404`, `405`, `409`, `502`, `503` y `504` según la operación.
* Mantén una cola o bloqueo por terminal para no enviar cobros concurrentes.

### Estado transaccional

* Persiste la referencia y los datos del cobro antes del envío.
* Confirma autorización con `success: true`, `resultCode: "00"` y `result.state: "AUTORIZADO"`. En consulta `200/00`, interpreta `transaction.state`. Ante cancelación fallida, evalúa un extorno independiente solo en CARD; conserva QR aprobado sin devolución.
* Interpreta `/cancel` por su respuesta. Ante fallo, timeout o incertidumbre, consulta el cobro original; no existe un GET de cancelación.
* Solo en CARD, verifica el extorno completado o en curso antes de solicitar otro; conserva abiertas las operaciones cuya resolución no puedas comprobar.
* Consulta la pasarela ante cobros sin verificar; `200/03`, `404/05`, `503` o `504` no confirman rechazo ni permiten otro cargo. Un extorno `UNKNOWN` con HTTP `502` requiere revisión; no confirma éxito.
* Recupera las operaciones abiertas después de un reinicio del sistema central.
* No conviertas un timeout o `404` de consulta en rechazo financiero.

### Decisión de negocio

* Define la acción que ejecutará el comercio después de una aprobación —por ejemplo, confirmar una venta o abrir una barrera— y cómo informará un rechazo o una cancelación.
* Define el límite de espera y el escalamiento de una operación no resuelta.
* Crea una referencia nueva solo después de resolver la operación anterior y verificar su resultado final. Distingue cancelación y rechazo por método, estado, código y mensaje.
* Conserva `authorizationCode` y `operationNumber` para el comprobante y la conciliación.

## Preparación del Wiseasy P5L

Alignet y el operador deben:

* instalar la versión de Pay-me PinPAD correspondiente al package `com.alignet.pinpad.ecr`;
* conectar el terminal a la red local y asignarle una IP estable;
* configurar la IP y el puerto de escucha, cuyo valor predeterminado es `8080`;
* confirmar la llamada real de `GET /health` desde el sistema central;
* completar la verificación de inyección de llaves;
* dejar la aplicación en **Listo para el siguiente vehículo**;
* confirmar que el terminal dispone de la conectividad necesaria para procesar el pago.

## Lista de verificación inicial

<Check>
  El sistema central y el Wiseasy P5L están en la misma red local y sin aislamiento entre clientes.
</Check>

<Check>
  La IP del terminal es fija o tiene una reserva DHCP.
</Check>

<Check>
  `GET /health` responde HTTP `200` desde el equipo donde se ejecuta el sistema central.
</Check>

<Check>
  El sistema central genera y persiste un `operationNumber` válido y único por cobro.
</Check>

<Check>
  `operationNumber` es un String de 1–64 caracteres sin espacios. `amount` es entero o String numérico positivo en unidades menores. Moneda y método son opcionales, con valores predeterminados `604` y `CARD`.
</Check>

<Check>
  El cliente maneja la consulta, idempotencia, concurrencia y reinicios.
</Check>

<Check>
  Está definido qué hacer ante un pago aprobado, rechazado o cuyo resultado aún no se conoce.
</Check>

<Check>
  Los logs de pruebas no contienen información sensible de tarjeta.
</Check>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.