Otra red, otro token: ¿dónde acabó el pago de tu cliente?

En Paymos, un pago en la red equivocada o con otro token no se esfuma. Acaba de una de tres maneras. El mismo token, enviado por otra red de las que admite la factura, la paga uno a uno sin que nadie intervenga. Otro token que Paymos admite en esa red entra solo en tu saldo, con la comisión de procesamiento de siempre, sin ticket de soporte y sin cargo por recuperarlo, mientras la factura agota su plazo y vence. Lo único que no llega por su cuenta es una transferencia en un token o una red que la factura no admite, o por debajo del mínimo de la red.

Saber cuál de los tres tienes delante decide qué le contestas al cliente y qué hace después tu sistema de pedidos. Si lo que falla es el importe, eso está en la guía de pagos de más y de menos. Aquí va el dinero que llega a la dirección de la factura sin pagarla: adónde va, cómo te enteras y qué recibe tu servidor.

¿Cuenta un pago que llega por otra red?

Sí, uno a uno, en casi todas las redes donde Paymos admite ese token.

El culpable es la dirección. Una dirección que empieza por 0x es idéntica en todas las redes que ejecutan la máquina virtual de Ethereum (EVM), y el centro de ayuda de MetaMask lo dice sin rodeos: la frase secreta de recuperación genera la misma dirección en todas las redes compatibles con EVM. Así que si la página de pago muestra una dirección en Polygon y el cliente elige BNB Smart Chain en el formulario de retiro de su exchange, la transferencia llega a esa misma dirección, solo que en otra cadena.

Paymos cuenta esa transferencia contra la factura como si la red hubiera sido la correcta. La factura se cierra, tu endpoint recibe los mismos eventos que habría recibido y el pedido sale como cualquier otro, sin que tengan que hacer nada ni tú ni tu cliente. En qué se diferencian las redes entre sí es otra comparación.

Si Paymos admite el token en esa red y aun así el pago no cuenta contra la factura, el dinero entra en tu saldo fuera de la factura, siempre que no quede por debajo del mínimo de la red, y la factura vence en su plazo. Cuando esa transferencia, sola o sumada a lo que ya se había pagado, cubre el importe, tu endpoint recibe después invoice.paid_late. El estado de la factura no cambia, paid_late_at guarda cuándo se alcanzó el importe y entregar o no el pedido lo decides tú.

Tron, TON y Solana usan cada una su propio formato de dirección, y una billetera de otra red no lo acepta como destino. Por eso los errores de red que llegan hasta una factura ocurren entre cadenas EVM.

¿Y si el cliente paga con otro token?

El dinero entra en tu saldo, siempre que Paymos admita ese token en la red por la que llegó. No hace falta abrir un ticket de soporte ni hay cargo por recuperarlo: solo se descuenta la comisión de procesamiento de siempre, la misma de cualquier pago liquidado, al porcentaje que figura en la página de precios.

Unos USDC enviados contra una factura en USDT entran como USDC: lo que se envió, menos esa comisión. No se convierte nada, y no hay tipo de cambio que los disfrace de importe de la factura. La factura no queda pagada, y otro token tampoco cuenta más tarde para su importe, así que no llega ningún invoice.paid_late. El abono queda marcado como pago con otro token, y el pedido que hay detrás espera a que decidas.

Lo que cuenta es el par: este token en esta red. Cada red tiene su propio contrato para un mismo token, y cada emisor publica su lista de redes, Circle la de USDC y Tether la de USDT. Los pares que admite Paymos están en /tokens/usdt y /tokens/usdc, y por qué un negocio se queda con un dólar digital y no con otro es una comparación aparte.

¿Por qué se canceló el pedido si el dinero está en tu saldo?

Porque la factura venció y tu servidor reaccionó al vencimiento. Es el único punto de tu integración que pide un cambio.

Un abono fuera de factura no tiene webhook propio: ninguno de los nueve eventos de factura del catálogo de eventos describe un abono. La factura que el dinero no llegó a pagar, sin embargo, sigue corriendo su plazo, y Paymos envía invoice.expired por ella; la documentación lo describe como «la factura venció sin un pago válido». Es cierto, y del dinero que ya está en tu saldo no dice una palabra.

El manejador que toca releer hoy es, entonces, el del vencimiento. Devolver el artículo al stock, liberar una plaza, cancelar el pedido, escribirle al cliente que su pago nunca llegó: cualquiera de esas acciones se ejecuta ahora sobre un pedido que alguien pagó.

// invoice.expired significa que la factura no se pagó.
// No significa que nadie enviara dinero a su dirección.
if (evento.event_type === 'invoice.expired') {
  await retenerParaRevision(evento.data.invoice_id); // ni cancelar ni reponer stock
}

Apartar un pedido vencido hasta que lo revise una persona también es lo más prudente con los vencimientos corrientes. Es el argumento de la idempotencia, visto desde otro ángulo.

A un pedido apartado le puede llegar una segunda señal. Si el dinero en el token de la factura, tardío o desde otra red, termina cubriendo el importe, llega invoice.paid_late por esa misma factura. El estado sigue en expired, así que el evento no cambia nada por sí solo: es una nota para el pedido apartado y el aviso para que quien lo revisa vuelva a mirarlo. Otro token nunca lo dispara.

¿Cómo te enteras del abono?

El aviso sale con el abono. Llega por correo, a la campana del panel y por Telegram si tienes ese contacto enlazado, por la misma vía que los avisos de retiro. El aviso trae el importe neto que entró en tu saldo, la comisión en una línea aparte, el token, la red, el motivo y un enlace al panel.

En la página Saldo, estos abonos viven en la pestaña Movimientos, en la misma tabla que tus retiros, y el filtro por tipo separa unos de otros. Cada fila indica si el dinero llegó con factura o sin ella, y de qué caso se trata: otro token, otra red, un pago fuera de plazo, una factura ya cerrada o una dirección sin factura. Su importe, con signo +, es lo que entró en tu saldo. Haz clic en la fila y se despliega en Bruto, Comisión, Neto, la Factura a la que pertenecía la dirección o Sin factura, Remitente, Transacción y una explicación breve. Si la transferencia de origen nunca se llegó a ver, la fila dice Remitente desconocido y Transacción desconocida, y los datos que aparezcan más tarde se suman a esa misma fila.

Para los abonos en sí no hay webhook ni llamada a la API: tu integración se entera por el panel y por el correo. El único evento que puede provocar este dinero es el invoice.paid_late de más arriba.

¿Entregar el pedido o devolver el dinero?

Lo decides tú, y lo que necesitas para decidir ya lo tienes delante. La factura se queda en expired elijas lo que elijas, aunque le haya llegado un invoice.paid_late; lo que está en juego es el pedido.

Entregar es cerrar el pedido a mano en tu propio sistema. Aquí la prueba del pago es la fila del abono y no el estado de la factura, así que copia sus datos en el pedido, donde tu equipo los vaya a buscar en la próxima conciliación.

Devolver es una transferencia desde tu saldo, por el importe, en el token y en la red que tú elijas. Nada vuelve solo, y el producto no le promete ninguna devolución a quien paga. La fila te da el material: cuánto entró, cuánto se llevó la comisión y, cuando se conocen, la dirección del remitente y el hash de la transacción.

Antes de prometerle nada al cliente, ten claros dos detalles. En tu saldo está lo que llegó menos la comisión, así que devolverle todo lo que envió te cuesta la diferencia. Y con el remitente desconocido no hay adónde mandar nada.

¿Cuándo no llega el dinero por su cuenta?

En tres casos, y en ninguno se abona automáticamente.

Un token que Paymos no admite en esa red, como USDC en Tron o en TON, o USDT en Base. Una transferencia así no se abona. Los pares admitidos están en /tokens/usdt, /tokens/usdc y /chains.

Una red que la factura no admite. Con una dirección 0x, el error realista está aquí. La misma dirección existe en cualquier cadena EVM, y ERC-7828, una propuesta de estándar dentro del propio proceso de Ethereum, habla de cientos de redes de segunda capa, y con el tiempo miles, que comparten el formato de dirección de la red principal de Ethereum. Son muchas más de las que admite Paymos. Un pago enviado por una de ellas se queda en esa dirección, en esa cadena.

Un importe por debajo del mínimo de la red. La página de pago de Paymos ya descarta de entrada el token y la red cuyo mínimo supera el importe de la factura, así que quien paga el importe completo en la red que le mostró la página no se topa con él. Sí se topa un pago parcial pequeño, o un desvío a una red con un mínimo más alto. Lo que queda por debajo del mínimo no se abona, y a partir de ahí lo lleva soporte.

¿Qué hace el cliente que ya envió el pago?

Escribir al vendedor con cuatro datos: el número de pedido, el token, la red y el hash de la transacción. Nada de lo que haga el cliente deshace una transferencia confirmada, porque un pago en blockchain no tiene marcha atrás y la billetera que lo envió no puede recuperarlo.

Al vendedor, porque todos los desenlaces terminan en él. Si el pago cerró la factura, el pedido sale igual que habría salido. Si se abonó fuera de la factura, el dinero está en el saldo del vendedor y la decisión es suya. Si no llegó por su cuenta, el hash es lo primero que va a pedir soporte. El cliente también puede escribir al soporte de Paymos desde la página de pago, y allí los operadores pueden sumar al vendedor a la conversación; los datos son los mismos cuatro.

De los cuatro, el que más pesa es el hash. Con él, el pago aparece en un solo paso y nadie tiene que cruzar importes con horas.

¿En qué se diferencia de un pago de más o de menos?

En si hay o no una factura detrás.

El pago de más y el pago insuficiente le ocurren a una factura. Cada uno tiene un estado que lee tu integración y un evento al que se suscribe —invoice.paid_over, invoice.underpaid, invoice.underpaid_waiting— y cada uno pertenece a un pedido que existe y está esperando algo. La guía del importe cubre los dos, y la de facturación explica cómo se emite una factura desde el principio.

Un abono fuera de factura es dinero sin factura detrás. No tiene estado ni evento propio, y el pedido al que parece pertenecer puede haber vencido, puede haberse cerrado semanas antes o puede no haber existido nunca.

Confundirlos lleva siempre al mismo error. Alguien del equipo ve el abono, lo toma por un pago parcial y entrega contra la factura; la factura no se completa jamás, y en la siguiente conciliación aparecen un abono y un pedido que nadie unió. La pregunta que los separa es qué factura está esperando ese dinero. Con un pago insuficiente, la respuesta está en la propia factura. Con un abono fuera de factura no hay ninguna, y el pedido lo cierras o lo devuelves tú.