Flujo de pago

Dos maneras de cobrar

Hay dos productos de cobro, y el que elijas cambia la forma de tu integración:

	Factura	Canal de pago
Qué es	Una sola petición de cobro	La identidad de cobro permanente de un cliente
Importe	Fijado al crearla	Ninguno: se abona cada depósito que alcanza el mínimo del token
Plazo	Sí	Nunca
Dirección	Una dirección propia por factura	Una dirección permanente por red, que nunca se reasigna
Estado final	paid, paid_over, underpaid, expired, cancelled	Ninguno: el canal sigue cobrando hasta que lo bloqueas
Va bien para	Página de pago, pedidos, cobros puntuales	Recargas de saldo, ingresos periódicos, clientes a los que facturas fuera de Paymos

El resto de esta página describe el ciclo de vida de una factura. Para la rama de canales, ve a Crear canal de pago: un canal no tiene ciclo de vida propio; lo tiene cada depósito que llega, y es mucho más corto — confirming → confirmed, con reorged en medio si la cadena se reorganiza.

Ciclo de vida

Toda factura termina en un único estado final: paid, paid_over, underpaid, expired o cancelled. La mayoría de las transiciones disparan un evento de webhook; la tabla de estados de más abajo indica cuáles. A partir de confirming las emiten todas. Los dos estados previos al pago no: nacer en awaiting_client es silencioso, y también lo es el paso normal a awaiting_payment cuando la página de pago confirma el token. La única excepción va hacia atrás: si un reorg profundo elimina todas las transferencias contadas, la factura retrocede a awaiting_payment y esa regresión sí emite invoice.awaiting_payment.

Dos formas de crear una factura

Ambas empiezan igual. La factura nace en awaiting_client, todavía sin dirección detrás. Lo que cambia es qué envías tú y cuánto le queda por decidir al cliente. La dirección se asigna —y la factura pasa a awaiting_payment— en el momento en que la página de pago confirma el token.

Flujo cripto directo — envía amount + currency + network. El amount es el importe en cripto que hay que pagar, y tanto el token como la cadena quedan fijados en la creación. Al cliente no le queda nada que decidir, así que la página de pago confirma ese par y la dirección se asigna de inmediato.

Flujo fiat — envía amount + currency (sin network). El amount es un importe en fiat. El cliente elige token y red en la página de pago; en ese momento Paymos fija el tipo de cambio, asigna una dirección y la factura pasa a awaiting_payment. El tipo fijado se lee de vuelta en la factura, en payment.exchange_rate, junto al importe exacto en token de payment.expected.

Consulta Monedas admitidas para la lista completa de códigos fiat y tokens, y Crear factura para el cuerpo de la petición.

Estados

Estado	Descripción	Evento de webhook
awaiting_client	Estado inicial de toda factura: no hay dirección hasta que la página de pago confirma el token	—
awaiting_payment	Dirección asignada, a la espera de la transferencia	— al entrar; invoice.awaiting_payment solo en la regresión por reorg
confirming	Pago detectado, a la espera de confirmaciones	invoice.confirming
underpaid_waiting	Se ha recibido un pago parcial, a la espera del resto	invoice.underpaid_waiting
paid	Pago confirmado por completo	invoice.paid
paid_over	El importe recibido supera al esperado (se abona íntegro)	invoice.paid_over
underpaid	Cerrada con pago insuficiente	invoice.underpaid
expired	El plazo venció sin pago	invoice.expired
cancelled	Cancelada por el comercio (solo desde awaiting_client)	invoice.cancelled

Cancelación

Una factura solo puede cancelarse mientras está en awaiting_client, antes de que la página de pago confirme el token. A partir de ahí la dirección está activa y al cliente se le ha comunicado un importe fijo en una cadena concreta, así que la cancelación deja de ser posible.

Plazos y vencimiento

Ajuste	Valor por defecto
Ventana para elegir token (flujo fiat)	Configurable
Vencimiento de la factura (tras asignar la dirección)	Configurable
Umbral de pago insuficiente	Configurable por proyecto
Tratamiento del pago de más	Se abona íntegro

Si el cliente envía menos del importe requerido antes de que la factura venza, el estado resultante depende de allow_multiple_payments:

• —allow_multiple_payments: true — el estado pasa a underpaid_waiting y se aceptan pagos adicionales hasta que venza el plazo
• —allow_multiple_payments: false — un único pago insuficiente cierra la factura de inmediato como underpaid

Si el plazo vence estando en underpaid_waiting, el estado final se resuelve a partir del importe total recibido y de la política de pago insuficiente. Si el cliente envía más de lo esperado, se abona el importe completo y el estado pasa a paid_over.