Solución de problemas - Alignet Integration Docs

Usa el código HTTP, status, resultCode y operationNumber para diagnosticar cada caso. No uses resultMessage como única base para la lógica del sistema central.

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	Timeout menor que la duración del cobro o pérdida de red.	No inicies otro cobro. Consulta el `operationNumber` original.
`202 PENDING`	Venció la espera, pero la operación puede seguir activa.	Consulta y respeta `Retry-After`.
`404 NOT_FOUND` al consultar	La referencia no existe o no coincide con la enviada.	Verifica el valor exacto y el terminal consultado. No asumas rechazo financiero.
Estado `UNKNOWN`	El terminal se reinició durante el proceso.	Mantén la operación abierta, consulta y aplica el escalamiento acordado.
Pago rechazado con HTTP `200`	`DENIED` es un resultado financiero válido.	No confirmes el pago. Un nuevo intento requiere otro `operationNumber`.

`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 numérico de 1 a 64 dígitos, sin letras, guiones ni otros caracteres;
amount: String numérico que representa un entero positivo de 1 a 12 dígitos en unidades menores;
currency: String numérico de exactamente tres dígitos;
paymentMethod: campo obligatorio; debe contener exactamente un valor, CARD o QR, en mayúsculas;
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.

POST sin respuesta
  → conservar operationNumber
  → GET /payments/{operationNumber}
  → repetir si responde 202
  → resolver solo con un estado final

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.
Respeta Retry-After; usa aproximadamente 2 segundos solo como referencia cuando el header no esté presente.
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;
código HTTP 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.

​Diagnóstico rápido

​GET /health no responde

​400 BAD_REQUEST

​Timeout o desconexión

​Operación pendiente por demasiado tiempo

​Datos para soporte