Solución de problemas

Usa HTTP, resultCode y operationNumber. En autorización interpreta success y result.state; en consulta a pasarela, success y transaction.state; en cancelación/extorno, status. No uses el mensaje como única base para decidir. El extorno 502 UNKNOWN utiliza el cuerpo compacto con message.

Diagnóstico rápido

Síntoma	Causa probable	Acción
`GET /health` no responde	IP o puerto incorrectos, firewall, aislamiento de clientes o aplicación cerrada.	Verifica la IP del terminal, la misma red local, AP/Client Isolation, puerto TCP y estado de Pay-me PinPAD.
`ping` no responde	Sin ruta IP o ICMP bloqueado.	Verifica direccionamiento. Si la red bloquea ICMP, prueba directamente `GET /health`.
`404` al autorizar	El sistema central llama a una ruta anterior o incorrecta.	Usa exactamente `POST /authorize`; no uses `/payment` ni `/api/v1/payments`.
`400 BAD_REQUEST`	JSON o campo inválido.	Revisa tipo, obligatoriedad, longitud y formato. Corrige antes de reenviar.
`409 POS_BUSY`	Existe otra operación activa.	Espera a que termine. Serializa los cobros por terminal.
`503 POS_NOT_AVAILABLE`	Pay-me PinPAD o el SDK de pagos no está listo.	El operador debe abrir la aplicación y dejarla en estado Listo.
El sistema central pierde la respuesta de autorización	Timeout menor que la duración del cobro o pérdida de red.	No inicies otro cobro. Consulta el `operationNumber` original mediante `GET /payments/{operationNumber}`.
Autorización `202 WAITING_RESULT` o extorno `202` en curso	Venció la espera, pero la operación puede seguir activa.	Usa el GET correspondiente y respeta `Retry-After: 2`.
`202` o timeout en cancelación	No hay cancelación confirmada.	Muestra Cancelación no confirmada, consulta `GET /payments/{operationNumber}` y respeta `Retry-After`.
`404/05` al consultar `/payments`	La operación no fue encontrada en la pasarela.	Verifica el valor exacto y el terminal consultado. No asumas rechazo financiero.
Consulta `/payments` con `200/03`, `503/P04` o `POS_NOT_AVAILABLE`, `504/SEARCH_TIMEOUT`	No se pudo verificar el cobro.	Conserva la referencia y consulta de nuevo o escala; no concluyas rechazo ni generes otra venta.
Timeouts o respuestas cruzadas al reutilizar sockets	El servidor cierra cada conexión.	Respeta `Connection: close`; abre una conexión por petición y desactiva keep-alive.
Extorno `502 UNKNOWN`	Búsqueda ambigua o vencimiento del control de espera.	La solicitud terminó sin confirmar éxito. Conserva el cuerpo compacto y solicita revisión financiera; no reintentes automáticamente.
`/cancel` con HTTP `200`, `DENIED`, incluido `14`	Cancelación rechazada o abandonada.	No registres cancelación exitosa; consulta el cobro original.
Pantalla cerrada tras procesar cancelación	El cierre visual no determina el resultado financiero.	Evalúa la respuesta de `/cancel`. Ante fallo o incertidumbre, consulta el cobro original; reconoce éxito solo si está validado.
Falla de conexión durante `/cancel`	No hay certeza de que el PinPAD recibió la solicitud o cerró la pantalla.	Muestra Cancelación no confirmada, recupera conexión y consulta la referencia original, sin repetir automáticamente el POST.
Fallo interno de `/cancel`	La pantalla puede haberse cerrado sin resolver la cancelación financiera.	Muestra Cancelación no confirmada y consulta el estado. El POST debe reflejar el fallo o pendiente real. Falta definir la respuesta específica cuando no se ejecutó o no coincide la operación.
QR `transaction.state: "AUTORIZADO"` en una consulta `200/00` sin solicitud de cancelación	Pago normal aprobado.	Confirmar pago y ejecutar la acción de negocio; no iniciar reversión.
Cobro CARD `transaction.state: "AUTORIZADO"` en una consulta `200/00` tras cancelación fallida	El cobro original sigue aprobado.	Evalúa un extorno independiente con `POST /reversals`; no lo ejecutes automáticamente ante cualquier error.
Pago QR confirmado durante cancelación	La transacción existía desde la generación del QR.	Ante cancelación fallida o incierta, consulta el cobro. Si aparece `transaction.state: "AUTORIZADO"` en una consulta `200/00`, conserva el pago aprobado y registra la discrepancia, sin refund ni reversa.
`/cancel` devuelve `409 CANCELLATION_IN_PROGRESS`	Ya se procesa otra cancelación de la misma referencia.	No repitas el POST. Conserva la referencia y recupera el cobro original si no recibes el resultado.
Método incorrecto en ruta válida	El método HTTP no está admitido.	HTTP `405`, `METHOD_NOT_ALLOWED`; corrige el método.
`202 WAITING_RESULT` tardío de `/authorize`	Venció la espera de esa solicitud.	Conserva el resultado confirmado y consulta si queda una discrepancia.

`GET /health` no responde

Sigue este orden:

Confirma en el Wiseasy P5L la IP y el puerto configurados.
Confirma que el sistema central usa esos valores y no una dirección anterior.
Verifica que ambos equipos estén en la misma red local.
Desactiva AP Isolation o Client Isolation para esos equipos.
Verifica que el firewall permita el puerto TCP configurado, 8080 por defecto.
Abre Pay-me PinPAD y confirma que la aplicación continúa en primer plano y lista.
Ejecuta nuevamente GET /health desde el mismo host y proceso de red que usará el sistema central.

Respuesta esperada:

{ "status": "UP", "service": "Alignet ECR" }

`400 BAD_REQUEST`

Verifica:

operationNumber: String de 1–64 caracteres sin espacios; conserva la referencia original y evita / para consultarla por ruta;
amount: entero JSON o String numérico positivo de 1 a 12 dígitos en unidades menores;
currency: número o String de exactamente tres dígitos; opcional, predeterminado 604;
paymentMethod: opcional, predeterminado CARD; acepta CARD o QR sin distinguir mayúsculas;
tollData: objeto opcional de valores String; se fusiona con additionalFields y prevalece en colisiones;
additionalFields: objeto opcional cuyos valores son únicamente String;
header Content-Type: application/json;
JSON bien formado.

Conserva el resultMessage para saber qué validación falló. No lo muestres sin control al usuario final.

Timeout o desconexión

Un timeout describe la conexión del sistema central, no el resultado financiero. El siguiente flujo corresponde a POST /authorize. Para una cancelación, conserva la referencia y aplica el procedimiento de /cancel. El extorno CARD es una acción independiente y tiene su propia consulta.

POST sin respuesta
  → conservar operationNumber
  → GET /payments/{operationNumber}
  → leer transaction.state si responde 200/00
  → consultar de nuevo o escalar ante 200/03, 404/05, 503 o 504
  → registrar solo un resultado confirmado

GET /payments puede tardar aproximadamente 12–15 segundos; usa un timeout de cliente de ejemplo de 20 segundos. No devuelve 202 ni estados locales. Confirma que el timeout del POST sea mayor que la espera interna del terminal. Con la referencia de desarrollo de 90 segundos, utiliza al menos 100 a 110 segundos.

Operación pendiente por demasiado tiempo

Mantén el mismo operationNumber.
Si el POST devolvió HTTP 202, respeta Retry-After: 2 antes de consultar. En las siguientes consultas a pasarela, aplica el intervalo y límite acordados.
Verifica que el terminal conserve conectividad local y conectividad con la plataforma de pagos.
Al alcanzar el límite acordado, inmoviliza la operación y escala. No crees automáticamente otra venta.

El límite máximo de consulta y la decisión de negocio deben definirse antes de producción.

Datos para soporte

Comparte:

ambiente, fecha y hora con zona horaria;
identificador del sistema central, punto de atención y Wiseasy P5L;
versión de Pay-me PinPAD;
IP y puerto, sin exponer información innecesaria fuera del canal de soporte;
operationNumber y paymentMethod;
cierre visual y secuencia de autorización, cancelación, consultas y extorno;
evidencia de extorno completado, en curso o todavía no verificable;
código HTTP, Connection, Cache-Control y Retry-After;
cuerpo de solicitud y respuesta sanitizados;
duración del POST y secuencia de consultas;
cambios de red o reinicios observados.

No compartas PAN completo, CVV, PIN, PIN Block, pistas ni datos EMV sensibles.

Operación y recuperación

Revisa el algoritmo de consulta, idempotencia y concurrencia.

Certificación y producción

Ejecuta los casos antes de habilitar cobros reales.

Guía

Integraciones

Diagnóstico rápido

`GET /health` no responde

`400 BAD_REQUEST`

Timeout o desconexión

Operación pendiente por demasiado tiempo

Datos para soporte

Operación y recuperación

Certificación y producción

​Diagnóstico rápido

​GET /health no responde

​400 BAD_REQUEST

​Timeout o desconexión

​Operación pendiente por demasiado tiempo

​Datos para soporte

Operación y recuperación

Certificación y producción

Diagnóstico rápido

`GET /health` no responde

`400 BAD_REQUEST`

Timeout o desconexión

Operación pendiente por demasiado tiempo

Datos para soporte