Facturar en criptomonedas: guía del ciclo de cobro

Facturar en criptomonedas enlaza un pedido con un pago vigilado en la cadena. La factura ata el identificador de pedido del comercio a un importe esperado, un vencimiento, las combinaciones válidas de activo y red, el estado del pago y el registro de la transacción resultante. Es el registro que hay detrás de cada método de cobro de Paymos.

Una dirección de billetera, por sí sola, no hace ese trabajo. No identifica el pedido, no decide cuándo el pago es definitivo y no le dice al sistema del comercio cuándo es seguro entregar. La factura aporta ese contexto comercial que falta. Para ver el modelo completo, lee cómo funcionan los pagos en cripto.

¿Qué datos necesita una factura en criptomonedas?

Una factura de producción responde a tres preguntas. ¿Qué debe el cliente, dónde puede pagar y cómo casará el comercio la transferencia con un pedido? Como mínimo, guarda el identificador de pedido del comercio, el importe solicitado, la moneda de precio, el vencimiento, el activo y la red elegidos, la dirección de destino, el estado de la factura y la referencia de la transacción en la cadena.

Mantén juntos el activo y la red en cada etiqueta que vea el cliente. «USDT» a secas está incompleto, porque USDT en Tron y USDT en Ethereum son activos distintos en cadena. Las instrucciones de pago también deben mostrar un código QR o una dirección que se pueda copiar, el importe exacto del token y un estado en vivo. El registro del comercio debe conservar tanto su propio ID de pedido como el ID de factura del procesador, para que soporte y conciliación puedan seguir cualquiera de los dos lados de la transacción.

¿Cómo evita duplicados la creación de facturas?

La creación de facturas tiene que ser idempotente a nivel de pedido comercial. Un tiempo de espera agotado deja al comercio sin saber si la primera petición llegó, y reintentar sin un identificador estable puede crear dos facturas cobrables para un mismo pedido.

Paymos usa para eso el external_order_id que envía quien llama. Reutilizar el mismo identificador externo de pedido devuelve la factura existente en lugar de crear otra. Paymos no usa una cabecera Idempotency-Key para crear facturas, así que la integración debe generar y guardar el identificador de pedido antes de su primera llamada a la API.

Guarda el ID de factura de Paymos junto al pedido original. Si se pierde la respuesta, repite la petición con el mismo external_order_id y continúa con la factura existente. Es más seguro que generar un identificador nuevo después de cada error de transporte.

¿Cómo recibe el cliente los datos de pago?

El cliente necesita una ruta de pago inequívoca antes de que su billetera envíe nada. Paymos puede presentarla en la página de pago alojada, en un iframe integrado, en un enlace de cobro, con el Low-Code SDK, con un plugin de CMS o en una interfaz propia construida sobre la API REST. Esa ruta debe mostrar el activo elegido, la red, el importe, la dirección, el código QR y el estado actual.

La página de pago alojada se ocupa de la interfaz de cobro. El pedido y la lógica de entrega siguen siendo del comercio. Un plugin de CMS conecta el mismo modelo de factura con una plataforma de comercio o de facturación admitida. La API REST encaja con equipos que necesitan una interfaz propia, pero también los hace responsables de la validación, el tratamiento de errores, las peticiones firmadas, la presentación del estado y la conciliación. Elige la vía con menos desarrollo propio que aún cumpla tu requisito de experiencia de producto.

¿Cómo es el ciclo de vida completo de una factura de Paymos?

Cambia la forma de integrarse, pero el bucle de control es siempre el mismo:

1. Crea la factura con un external_order_id estable.
2. Presenta una ruta disponible de activo y red desde la página de pago, un enlace, un plugin, un widget o tu propia interfaz.
3. Deja que la billetera de quien paga envíe el importe y cubra la comisión de red de entrada.
4. Espera mientras Paymos aplica la política de confirmación de esa red y ese importe.
5. Aplica la tolerancia de pago insuficiente del proyecto al importe realmente recibido.
6. Verifica y guarda de forma duradera la entrega del webhook firmado antes de entregar el pedido.
7. Concilia el ID de pedido, el ID de factura de Paymos, el importe recibido y la referencia de la transacción en la cadena.

Esta secuencia enseña dónde encaja cada control. El de duplicados, la finalidad, el pago insuficiente y la entrega valen igual en todas las vías de integración admitidas. La forma exacta de la petición depende de la vía elegida. Los equipos que construyen un camino propio pueden completarla con la guía de cobro por API REST.

¿Cuándo es seguro entregar un pago detectado?

Detectar no es alcanzar la finalidad. Un procesador puede observar una transacción antes de que la red dé confianza suficiente de que seguirá en el historial canónico. La factura solo debería pasar a un estado listo para entregar cuando se haya completado la política de confirmación aplicable.

Paymos fija la política de confirmación por red y por importe del pago. Los pagos pequeños pueden exigir menos confirmaciones, mientras que los grandes pueden esperar a un umbral más exigente. No existe un único tiempo de confirmación válido para todas las facturas. Las condiciones de la red también cambian el tiempo que transcurre.

Entrega solo desde el estado final de pagada. No te fíes nunca de una captura de la billetera, de un hash de transacción que aporte el cliente ni de un primer aviso de «transacción vista». La guía de confirmaciones en blockchain explica por qué varía la profundidad exigida.

¿Cómo funciona la tolerancia de pago insuficiente?

El pago insuficiente sigue un porcentaje definido por proyecto. No depende de lo que decida un agente de soporte sobre la marcha. El control va del 0 % al 2 % en pasos de una décima y un proyecto nuevo nace con 0,1 %: cubre una cola de redondeo y nunca llega a ser un descuento. Con 0 % la coincidencia es estricta, es decir, el pago iguala la factura o la supera. Si el importe recibido cae dentro de la tolerancia configurada, la factura se cierra y el comercio liquida el importe pagado. La parte que falta no se añade.

Si una factura de un solo pago se queda por debajo del umbral, sigue marcada como pago insuficiente. Si la factura admite varios pagos, puede seguir abierta mientras el cliente envía el resto. La integración debería mostrar ese estado en lugar de dar el pedido por pagado en silencio.

Fija la tolerancia según la economía del pedido. Un porcentaje pequeño puede absorber el redondeo de una billetera sin generar trabajo manual, pero una tolerancia amplia puede convertir un error de precio en un descuento aceptado en cada factura.

¿Cómo se procesan los webhooks firmados de una factura?

Los webhooks llevan el estado de la factura al sistema del comercio. Paymos los firma con HMAC-SHA256 en la cabecera X-Webhook-Signature, con el formato t={timestamp},v1={hmac_hex}. El servicio que recibe debería verificar la marca temporal y la firma con una comparación de tiempo constante antes de tratar el evento como dato de confianza.

La entrega se reintenta, así que los manejadores tienen que ser idempotentes. Un ciclo de entrega de Paymos hace 11 intentos en total —uno inicial y diez reintentos— a lo largo de unas 16 horas. Los eventos fallidos o no entregables se pueden reenviar a mano.

Responde con éxito solo cuando el evento esté guardado de forma duradera. Ejecuta después la entrega del pedido a partir de ese registro. Si falla un trabajo posterior, reinténtalo por dentro en lugar de pedirle al emisor que repita un evento cuya recepción ya estaba guardada.

X-Webhook-Signature: t=1785326400,v1=2b4f...
Content-Type: application/json

¿Qué debe guardar la conciliación?

La conciliación debería crear un rastro completo. Conecta el pedido comercial, el registro del procesador y la transacción en la cadena. Guarda el identificador externo de pedido, el ID de factura de Paymos, los importes solicitado y recibido, el activo, la red, la referencia de la transacción, el estado final y las marcas temporales relevantes. Conserva también la clave de procesamiento que define el comercio para evitar trabajo duplicado.

Concilia a partir del estado del procesador, no de un hash de transacción que aporte el cliente. Una transferencia puede usar el activo equivocado, la red equivocada, la dirección equivocada o un importe insuficiente y aun así parecer plausible en un explorador de bloques. El estado de la factura evalúa la transferencia frente a la petición de pago.

El soporte debería encontrar el registro por tres identificadores. El ID de pedido, el ID de factura y la referencia de la transacción tienen que llevar al mismo rastro. Eso reduce errores en las devoluciones y le da al comercio un historial defendible cuando un cliente discute la entrega.

¿Qué vía de facturación en cripto conviene elegir?

Usa un enlace de cobro para facturas manuales ocasionales. Encaja cuando quien cobra es ventas o soporte. Usa la página de pago alojada o el pago integrado cuando una web necesite una página de cobro completa sin hacerse cargo de cada interacción con la billetera. Usa un plugin oficial de CMS cuando la tienda funcione sobre una de las plataformas admitidas por Paymos.

Elige la API REST para un flujo realmente propio. Paymos separa las credenciales de Sandbox y de producción, pero mantiene la misma superficie de API, así que un equipo puede probar resultados de facturas y el tratamiento de webhooks antes de mover fondos reales. Las credenciales Payment y Payout también siguen siendo independientes.

Mantén el mismo bucle de control en todas las vías. Crea con un identificador externo de pedido estable, muestra datos de pago exactos, espera al estado final de pagada, verifica los webhooks firmados y concilia antes de entregar.