Asociación de pagos y discrepancias de importes

Esta sección describe la regla con la que el servicio asocia una transacción on-chain entrante a una factura emitida, qué ocurre cuando el importe difiere y qué puede hacer el comercio en ese caso.

Los estados de la factura, los plazos y las transiciones de estado se describen en Ciclo de vida de la factura.

La regla de coincidencia de importes

Al crear la factura, el servicio convierte el importe fiat a cripto y fija los importes resultantes para la factura. Estos se convierten en el identificador del pago: el cliente los ve en el formulario de pago, y el servicio busca on-chain una transacción exactamente por ese importe.

El importe del pago debe coincidir exactamente con el de la factura. No hay tolerancia. El importe a pagar se forma con 2 decimales para las stablecoins USDT y USDC y con 8 decimales para las demás criptomonedas, y el pago entrante se compara con él con precisión. Cualquier desviación —pago insuficiente o en exceso, por pequeña que sea— significa que no habrá asociación automática.

Ejemplo. Se emite una factura de 100.00 USD con un importe fijado de 100.12 USDT.

Importe del pago entrante	Resultado
100.12 USDT	La factura pasa automáticamente a Pagada
100.11 USDT	Sin asociación automática
100.50 USDT	Sin asociación automática

Si se emiten a la vez varias facturas por el mismo importe fiat a una misma dirección, el servicio asigna a cada una un importe en cripto ligeramente distinto. La unicidad se comprueba entre todas tus facturas sin pagar de esa billetera, así que una misma dirección puede usarse sin problema en varios de tus proyectos —los importes no colisionarán.

Las causas más comunes de una discrepancia son que el cliente redondee el importe a mano o que la comisión de red se descuente al retirar desde un exchange. Advierte al cliente de que transfiera exactamente el importe que muestra el formulario de pago.

Qué ocurre con una discrepancia de importes

El servicio registra que los fondos llegaron, pero no hace nada con la factura:

• La factura no cambia de estado. Sigue sin pagar hasta el plazo de pago. El cliente aún puede cerrarla con el importe correcto mientras la ventana de búsqueda esté abierta.
• No se envía ningún webhook. La notificación al Webhook URL sale solo en el momento en que la factura pasa a Pagada.
• El pago parcial no se registra. El servicio no reconoce el pago insuficiente y no lleva un saldo pendiente de la factura.
• Los pagos no se suman. Si tras un pago insuficiente el cliente envía una segunda transacción por la diferencia que falta, los dos pagos no se suman. Ambos quedan como pagos separados sin asociar.
• El pago en exceso no se reembolsa automáticamente. Los fondos van directo a tu billetera; devolver la diferencia al cliente se gestiona fuera del servicio.

En el servicio no hay estados intermedios como Pagada parcialmente o Pagada en exceso.

Cómo se entera el comercio del problema

Si las notificaciones están activadas en la configuración del proyecto, el comercio recibe un correo y un mensaje del bot de Telegram por cada pago entrante —haya coincidido o no con una factura.

Esto da una regla de diagnóstico sencilla: si llegó una notificación de pago entrante pero no la siguió una de factura pagada, el pago no coincidió por una discrepancia de importes y requiere gestión manual.

La regla funciona solo dentro de la ventana de búsqueda. El servicio vigila las billeteras solo mientras al menos una factura mantenga una búsqueda activa. Si el cliente paga cuando no existen tales facturas, el pago no entra en el sistema en absoluto —ni notificación, ni forma de asociarlo manualmente.

También puedes encontrar los pagos sin asociar por programa. El método payments/list devuelve los pagos de todas tus billeteras, y un pago no asociado a una factura no tiene el bloque invoice en la respuesta. Esos son los candidatos a la asociación manual: compara el importe y la hora con la factura esperada y llama a invoices/bindPayment.

Asociación manual de pagos

Si tienes la certeza de qué pago corresponde a qué factura, asócialos manualmente —en el panel, en la página de la factura o en la lista de pagos, o a través de la API con el método invoices/bindPayment.

Condiciones de la asociación

La asociación solo es posible cuando se cumplen todas las condiciones a la vez:

1. La factura está Sin pagar o Vencida. Las facturas canceladas y las ya pagadas no se pueden asociar.
2. El pago aún no está asociado a otra factura. Un pago solo puede vincularse a una factura.
3. El pago llegó a una billetera que participa en esta factura.
4. El pago cae dentro de la ventana de pago disponible —24 horas antes y 24 horas después de la creación de la factura.

La ventana es más amplia que la validez de la factura, lo que abre dos posibilidades: puedes asociar un pago a una factura ya vencida y puedes asociar una factura a un pago que llegó antes de crearse la factura. Lo segundo resulta útil cuando el cliente envió el dinero por iniciativa propia y la factura se emitió después de recibirse los fondos.

Qué ocurre después de la asociación

• La factura pasa a Pagada —igual que con la asociación automática.
• El webhook se envía siempre. La notificación sale en cada transición a Pagada, sin importar cómo se hizo la asociación.
• El importe de la factura en USD se recalcula a partir del pago real. El campo amountFiatUSD se sobrescribe con el importe realmente recibido, al tipo de cambio del momento de la asociación. El importe original en amountFiat no cambia.
• La comisión se recalcula a partir del importe real. Se cobra según la tarifa del proyecto sobre el importe que recibiste.