Conceptos

Concepto	Qué es
Comercio	La entidad que cobra. Su client_id (UUID) identifica sus credenciales. Debe tener un akua_merchant_id configurado para cobrar con tarjeta y PSE.
Link de pago	Un cobro reutilizable o de un solo uso con un monto, un concepto y un vencimiento. Su dirección pública es /l/{token}.
Página de pago	La página hospedada por la pasarela que abre el pagador a partir del link.
Medio de pago (rail)	Cómo paga el pagador: card, pse, cuentas_crezcamos, bre_b.
Pago	El intento de cobro de un link con un medio. Hoy nace dentro de la pasarela, no se crea por API.
Evento	Una notificación que la pasarela envía al comercio (por ejemplo payment.approved).
Proveedor de medio de pago	Un tercero (Mo$i, Bre-B…) que procesa el pago fuera del checkout y lo confirma a la pasarela.

Estados del link de pago

active → payment_in_progress → (redirected) → paid | failed | in_review; además expired, revoked, exhausted, refunded, closed. Tabla completa en estados.

Estados del pago

pending, payment_in_progress, redirected, in_review, paid, failed, refunded, closed.

El estado del pago es el que cuenta

Para saber si un cobro se completó, usa el evento payment.approved (o el estado paid del pago en el webhook). Nunca confirmes un pedido porque el pagador volvió a tu sitio: el retorno del navegador no es una prueba de pago.

Formato

• JSON:API (application/vnd.api+json): { "data": { "type", "id", "attributes" } }.
• Importes en COP; en los webhooks los importes viajan como texto ("50000").
• Fechas en ISO 8601 (UTC).