¿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.

Ninguno de los dos casos es raro cuando cobras en cripto. La mayoría de tus clientes no paga desde una billetera propia, paga desde la cuenta de un exchange que descuenta su comisión del importe que manda; 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 ocho 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.

Lo que falta casi siempre sale de una cuenta de exchange. 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». Tu cliente tecleó el importe de la factura, el exchange envió ese importe menos su comisión, y a tu factura le falta exactamente 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.

Con varios pagos permitidos, uno corto no cierra nada. 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 apagada, un pago corto es el final. 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 corta que siga sin cubrirla 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 en la página de saldos los dos se parecen bastante. 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 la factura no se toca. No queda pagada ni queda como pago insuficiente: no cambia de estado.

Tampoco hay evento. No uno distinto: ninguno, porque un abono de esta clase no tiene nada en el flujo de webhooks que lo lleve. 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, y nada que tu servidor pueda escuchar.

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" }

overpaid paga un 10 % por encima del importe esperado y underpay paga el 40 %; todas las cifras salen de la factura en el servidor y el cliente no manda ninguna. Las etapas suman entre llamadas, así que dos underpay dejan un 80 % contra la misma factura y sigue corta.

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.