Diagnóstico de un pago

Seguir un pago

Un pago pasa por: link (active) → el pagador elige un medio → pago (in_review mientras espera) → resultado (paid o failed) → webhook al comercio. Mira cada paso.

1. El link

curl -s "$API/api/payment-links" -H "Authorization: Bearer $TOKEN"

Si el pagador ve "Link no disponible", el estado del link no es active (pagado, vencido, revocado, o hay un intento en curso). Ver estados.

2. El pago y los eventos (base de datos del motor)

-- Pagos recientes
select provider_payment_id, rail, provider, state, status_detail, amount, provider_reference, updated_at
from payments order by inserted_at desc limit 20;

-- Eventos recibidos y enviados
select direction, provider, event_type, status, external_event_id, attempt_count, inserted_at
from webhook_events order by inserted_at desc limit 20;

En el kind local: kubectl --context kind-pe-test -n payment-engine exec postgres-0 -- psql -U postgres -d payment_engine_dev -c "…".

3. Los servicios

kubectl -n payment-engine logs deploy/payment-engine-api       # webhooks entrantes, API
kubectl -n payment-engine logs deploy/payment-engine-web       # página de pago, errores del proveedor
kubectl -n payment-engine logs deploy/payment-engine-worker    # entrega de webhooks salientes

Problemas frecuentes

Síntoma	Causa probable	Qué hacer
401 con The issuer '…' is invalid	El token se pidió a Keycloak por una dirección distinta de la pública configurada	Pedirlo por la dirección pública; ver autenticación.
Pago pendiente tras pagar por PSE	El webhook del proveedor no llegó o falló la firma	Revisar webhook_events (status, attempt_count) y los logs de la API. En el simulador, mirar el outbox de pse-sandbox.
La respuesta de PSE dice "enlace de retorno no válido"	El link de retorno venció o el pago no se encuentra por su referencia	Abrir de nuevo el retorno; verificar provider_reference del pago.
El comercio no recibe webhooks	No hay webhook registrado, filtro de events que no coincide, el worker no corre, o se agotaron los 5 intentos	Listar GET /api/merchant-webhooks; revisar el worker y webhook_events. No hay reenvío manual aún.
"No pudimos iniciar el pago con tarjeta" en local	El simulador no implementa /v1/links	Esperado en el entorno local; probar tarjeta contra Akua real.
El banco elegido no cambia lo que llega al proveedor	Está configurado el bank_id forzado (AKUA__PSEBANKIDOVERRIDE, por defecto 1007)	Dejarlo vacío para enviar el banco elegido.
Mo$i/Bre-B: el webhook responde 422 amount mismatch	El monto del evento no coincide con el total del link	Enviar el monto del link (o no enviar amount).
Mo$i/Bre-B: 422 payment not found	El primer evento no trae payment_link_token	Enviar el token del link.