¿Qué pasa si el cliente paga de más o de menos?

Un cliente paga 49,6 USDT contra una factura de 50. No se equivocó: su exchange le restó la comisión de retiro del importe que envió, la transferencia está confirmada y no hay reversión que pedir. Lo que ocurre a partir de ahí quedó decidido antes de que abriera la página de pago. Un importe por encima del pedido entra entero en tu saldo y cierra la factura como pagada; uno por debajo tiene dos finales, y un ajuste del proyecto elige cuál.

Un exchange puede descontar su comisión del importe que envía; las cotizaciones arrastran decimales que nadie teclea enteros; y quien completa un pedido redondea a una cifra que le parece limpia.

Esta página va del importe. Crear la factura es otra guía, y la máquina de estados completa vive en el flujo de pago. Lo que sigue es qué le hace cada final a tu saldo, a tu pedido y a los eventos que escucha tu servidor.

¿Qué pasa con el dinero que sobra?

No se retiene nada.

El importe que llegó entra entero en tu saldo, excedente incluido, y la factura cierra como pagada. La comisión de procesamiento sigue la regla de cualquier otro pago: cae sobre lo que entró y no sobre lo que pediste, así que el excedente paga la misma comisión que el resto de la transferencia. El porcentaje está en la lista de precios.

Devolver lo que sobra es una transferencia tuya. Nada sale solo, y la decisión es comercial antes que técnica: una cola de decimales no compensa una transacción, y quien tecleó un cero de más te escribe antes de que tú te enteres.

El evento no se llama como lo espera tu código

Un pago que cae justo en la cifra avisa con invoice.paid. Uno que se pasa avisa con invoice.paid_over, y ese nombre es toda la diferencia que recibe tu sistema.

El evento te llega, eso no falla. Una suscripción de webhook se toma por categoría y los nombres sueltos de dentro no se eligen uno a uno, así que un endpoint suscrito a la categoría de facturas recibe los nueve eventos, con invoice.paid_over entre ellos. Llega, el manejador compara el tipo con invoice.paid, encuentra otra cosa y lo archiva entre lo que no le interesa.

El fallo es silencioso por construcción. El panel enseña una factura pagada, el abono está en el saldo, el pedido sigue sin salir y nadie devolvió ningún error. Aparece días más tarde, cuando escribe un cliente preguntando por su pedido, y elige justo a los clientes que te pagaron de más.

Compara contra un conjunto y no contra una cadena:

// Las dos cierran la factura. Solo la segunda trae excedente.
if (in_array($evento['event_type'], ['invoice.paid', 'invoice.paid_over'], true)) {
    entregarPedido($evento['data']['invoice_id']);
}

Y guarda las dos cifras por separado en tu propio registro. Lo pedido y lo recibido son números distintos, y el excedente es la resta entre ellos — no algo que deducir más tarde del nombre de un evento.

¿Por qué llegan importes cortos?

La comisión de red es el sospechoso habitual y es el equivocado.

El gas de Ethereum se paga en ether y no en el token que viaja: «Las tarifas de gas deben pagarse en la moneda nativa de Ethereum, el ether (ETH)», dice la documentación de la propia red. La billetera que envía lo cubre de su saldo de moneda nativa, y el importe del token llega intacto. Quien manda 50 USDT desde una billetera suya manda 50 USDT.

Una retirada desde un exchange puede dejar un importe pendiente. Binance aclara en su soporte que esa comisión no se la queda la casa: «Esta comisión no se abona a Binance, sino a los mineros o validadores, responsables de procesar las transacciones y de garantizar la seguridad de la red de cadena de bloques correspondiente». Y su centro de ayuda estadounidense dice de dónde sale el dinero: «Both Binance.US operational fees and network fees are deducted from your withdrawal amount before it reaches your destination wallet». Si tu cliente introduce el importe de la factura y el exchange descuenta su comisión, a la factura le falta esa comisión.

Por eso la tolerancia es un porcentaje y la causa no lo es. Un descuento fijo se come un pedazo visible de una factura pequeña y una miseria de una grande, así que ningún porcentaje cubre las dos. Con un 0,1 %, una factura de 50 absorbe cinco centésimas: una cola de decimales, y nada parecido a la comisión de un exchange. Ajusta la tolerancia para los decimales y trata el caso del exchange por lo que es, algo que contarle a quien paga en la página de pago o en el correo de confirmación.

¿Cuánto puede faltar y aun así contar como pagada?

Cada proyecto lleva su Tolerancia de pago insuficiente, y a nadie se le pregunta cuando un pago se queda por debajo. El techo es el 2 %, el control se mueve de décima en décima y un proyecto que crees hoy nace en el primer escalón, el 0,1 %. Bájalo a cero y entra el modo estricto: el pago tiene que igualar el importe de la factura o superarlo. No hay excepción por factura, porque la petición de creación no lleva ningún campo de tolerancia: lo que diga el proyecto es lo que hereda cada factura que salga de él.

Dentro de la tolerancia la factura se completa y avisa con invoice.paid, igual que cualquier otra factura pagada. Liquidas el importe que llegó; la diferencia no la pone nadie.

Un detalle decide qué puedes arreglar después. A una factura la juzga la tolerancia que tenía su proyecto el día en que se creó, y esa copia queda congelada en la factura el resto de su vida. Mueve el control y habrás cambiado las facturas que emitas a partir de ahora, no las que ya están abiertas en una página de pago.

Dos finales para un pago corto

allow_multiple_payments elige entre ellos, queda fijado al crear la factura y la API lo trae en true.

Si se permiten varios pagos y falta más de lo tolerado, la factura sigue abierta. La factura pasa a underpaid_waiting y sigue abierta por lo que falta, y la página de pago hace la resta por quien paga: el QR y cada enlace de billetera se rehacen sobre el importe pendiente, calculado en el servidor en lugar de restado en el navegador. En la tarjeta de Telegram, el botón de copiar el importe se renombra y copia lo que falta en vez del total original.

Con la opción desactivada, la factura se cierra si falta más de lo tolerado. La factura cierra en underpaid y avisa con invoice.underpaid.

El reloj termina las que quedan abiertas. Cuando la ventana de pago se cierra sobre una factura que sigue por debajo, se liquida como pago insuficiente, salvo que una transferencia detectada se esté confirmando: entonces el vencimiento no ocurre, porque una factura no vence por debajo del dinero que ya va de camino.

El saldo se mueve aunque la factura no cierre

Se mueve, y en un extracto eso se lee raro.

Cada transferencia se abona en cuanto confirma, y la comisión cae sobre el importe de esa transferencia, así que un pago parcial es dinero en tu saldo con la factura todavía abierta. Una factura que termina en underpaid te deja con fondos de verdad contra un pedido que nunca cerró.

Los eventos son más callados que el dinero. invoice.underpaid_waiting sale una vez, cuando la factura entra en ese estado. Una segunda transferencia que aún deje un faltante superior a la tolerancia mueve tu saldo otra vez y no produce ningún evento nuevo, porque el estado no cambió y un webhook se encola al cambiar de estado. Una pantalla de soporte construida sobre el flujo de eventos enseñará una llegada donde hubo dos. El total acumulado está en la factura.

Queda la decisión que nadie toma por ti: servir igual, servir una parte, pedir la diferencia o devolver el dinero. Devolverlo es una transferencia corriente desde tu saldo, como en el sobrepago.

Dinero que entra y no paga ninguna factura

Una factura puede quedarse corta. También puede llegar dinero que nunca fue pago de ninguna factura, y con solo mirar el saldo no los distingues. No se comportan igual en nada.

Cada abono guarda su motivo, y los del día a día son estos: una transferencia que llega con la ventana ya cerrada, otra contra una factura que cerró antes, alguien que manda USDC a una factura puesta en USDT, y un ingreso a una dirección sin factura detrás. Los cuatro entran en tu saldo menos la comisión de procesamiento de siempre, y el estado de la factura no se mueve: no queda pagada ni como pago insuficiente.

El abono tampoco tiene evento propio. Un pago insuficiente tiene un estado que tu integración lee y un evento al que suscribirse. Esto tiene una línea en la página de saldos, un correo, un aviso en la campana del panel y un mensaje de Telegram cuando el contacto está enlazado. Un caso sí llega a tu servidor: si la factura venció o cerró como pago insuficiente y el dinero tardío en su token cubre el importe, solo o con lo que ya había, la factura guarda paid_late_at y envía invoice.paid_late una sola vez, sin cambiar de estado. Un pago tardío parcial, otro token o una dirección sin factura no envían nada.

La diferencia decide dónde mirar cuando los libros no cuadran. Una factura corta es un pedido al que perseguir. Un abono sin factura detrás es dinero que alguien te mandó y que ningún pedido está esperando: solo el saldo te va a decir que está ahí.

Ensáyalo en Sandbox antes que un cliente

Con el simulador de pagos, que emite los mismos webhooks de ciclo de vida que produce un pago real. Una llamada firmada lleva una factura de sandbox ya confirmada hasta el final que quieras probar:

POST /v1/sandbox/invoices/inv_7Qk2.../simulate-payment
Content-Type: application/json

{ "stage": "overpaid" }

paid paga lo que queda pendiente. overpaid cubre ese importe y añade un exceso positivo aleatorio; underpay paga una parte positiva aleatoria del pendiente. Si se permiten varios pagos, puedes repetir underpay y los pagos se acumulan. De lo contrario, la factura se cierra como underpaid. El servidor calcula los importes; tú solo indicas la etapa.

Tres pruebas valen la pena antes de la primera de verdad:

1. overpaid contra una factura que vigile tu ruta de entrega. El pedido tiene que salir, y tu propio registro tiene que enseñar recibido por encima de pedido.
2. underpay contra una factura que admita varios pagos. El pedido no sale, y lo que mire tu equipo de soporte tiene que enseñar lo que falta y no el total original.
3. underpay contra una factura creada con allow_multiple_payments en false. El pedido no sale y la factura cierra.

La rama de la tolerancia es la única que no se ensaya así. No hay etapa que pague una fracción de menos, así que ese ajuste se comprueba leyéndolo en el proyecto y no disparándole una prueba. Todo lo demás está a una petición firmada de distancia.