Cómo funciona una pasarela de pagos con criptomonedas

Una pasarela de pagos con criptomonedas se ubica entre un negocio y las blockchains: le da al pagador una dirección y un monto, vigila la red, decide cuándo el dinero cuenta como recibido y se lo informa a los sistemas del negocio. Este artículo sigue un pago de CryptoLike desde que se crea hasta el retiro, paso a paso, con los estados y eventos que ve tu integración en cada punto. Para ver las formas de conectar un sitio web, lee la guía sobre cómo recibir pagos con criptomonedas.

#¿Qué es una pasarela de pagos con criptomonedas?

Una pasarela de pagos con criptomonedas es un servicio que recibe cripto en nombre de un negocio e informa el resultado en términos de negocio: pagado, pago insuficiente, vencido. CryptoLike es una plataforma de procesamiento de pagos cripto: los negocios reciben Bitcoin, Litecoin, Ethereum, TRON y las stablecoins USDT/USDC mediante una API REST, plugins para CMS, enlaces de pago y una página de pago alojada, y hacen retiros desde un solo saldo.

Sin una pasarela, un negocio tendría que publicar la dirección de su propia billetera, asociar a mano las transferencias entrantes con los pedidos, contar confirmaciones y convertir precios por su cuenta. La pasarela convierte cada una de esas tareas en un campo de un solo objeto —el pago— con un solo estado, el mismo en la API, en la página de pago y en los webhooks.

Cómo se ve esto en la práctica depende del negocio: una tienda online conecta un plugin, un servicio de bienes digitales o SaaS llama a la API, y un servicio con saldos de usuarios le da a cada usuario una dirección de depósito estática. Los pasos de abajo son los mismos para los tres. Si todavía comparas proveedores, revisa las 10 preguntas para elegir una pasarela de pagos cripto.

#Paso 1. Se crea el pago

Todo pago de CryptoLike empieza como un objeto con un monto, una moneda y un plazo, creado con el estado new (Nuevo). Su precio puede estar en una moneda cripto (USDT, BTC) o en fiat (USD, EUR). Lo crea tu servidor con POST /v1/invoices, un plugin para CMS al finalizar la compra, o tú desde el panel como factura o enlace de pago.

La respuesta trae checkout_url —la página a la que envías al pagador— y ttl_expires_at, el plazo límite. El plazo se fija para cada pago con ttl_seconds (de 60 segundos a 30 días) o se toma de la configuración de tu cuenta. Dos protecciones evitan que un reintento cree un segundo pago: el encabezado Idempotency-Key repite la misma respuesta durante 24 horas, e idempotency_by_order_id devuelve el pago abierto de un pedido en lugar de crear otro.

Otras formas de crear el mismo objeto: un enlace de pago desde el panel o el bot de Telegram, o una factura cripto enviada a un cliente. Todas llevan a la misma página de pago.

#Paso 2. El pagador abre la página de pago

La página de pago de CryptoLike muestra todos los parámetros clave antes de que el pagador actúe: el monto a enviar, el activo y su red, la dirección con un código QR y el tiempo restante. Si no fijaste el activo, el pagador primero elige con qué pagar entre las monedas que ofreces, cada una con un monto aproximado marcado con ≈; el tipo de cambio se fija en ese momento y no cambia hasta que el pago vence. Los íconos de los tokens, como USDT, llevan una pequeña insignia de su red.

Junto a la dirección, la página muestra un aviso de red; por ejemplo: «Envía a esta dirección solo BTC en la red Bitcoin. Los fondos enviados por otra red no se pueden recuperar.» El estado en la página se actualiza en vivo, así que el pagador no necesita recargarla. La página se abre como página alojada o dentro de tu propio proceso de compra con el widget de pago.

#Paso 3. Se detecta la transferencia: pending

En cuanto la transferencia del pagador aparece en la red, el pago de CryptoLike pasa a pending (Pendiente) y la página dice «Pago detectado. Esperando confirmación.» El monto detectado se muestra de inmediato, así que un faltante se ve antes de cualquier confirmación. El monto se registra en tu saldo pending, pero todavía no hay nada disponible para gastar: en esta etapa, una transferencia aún puede desaparecer de la cadena.

Tu servidor recibe invoice.pending con el id de la transacción en details. No entregues el pedido con pending: solo te indica que el cliente envió algo.

#Paso 4. Se acumulan las confirmaciones

Una confirmación es un bloque construido encima del bloque que contiene la transferencia. CryptoLike acredita un pago solo cuando la transferencia alcanza el umbral de confirmaciones de su activo. El umbral se fija por activo, se publica en GET /v1/currencies y en la página de monedas, y el pagador lo ve como «n de N confirmaciones, normalmente unos X min».

El umbral protege contra las reorganizaciones de bloques, cuando la red reemplaza bloques recientes y una transferencia puede desaparecer. Si una reorganización revierte una transferencia que ya estaba confirmada, el pago se recalcula y recibes invoice.reverted. El artículo sobre las confirmaciones de un pago cripto explica por qué los umbrales varían entre redes; el catálogo de monedas lista los activos.

#Paso 5. Pagado, y un webhook firmado

Cuando el monto confirmado cubre el pago —un faltante dentro de una tolerancia pequeña (0.5 % de forma predeterminada) igual cuenta—, CryptoLike cambia el estado a paid (Pagado), acredita los fondos a tu saldo y envía invoice.paid. El pagador ve «Pago confirmado.» y, si configuraste return_url, un enlace de regreso a tu sitio. paid es definitivo: entrega el pedido con este estado. Un pago excedente sigue siendo paid, con overpaid_amount mayor que cero.

Cada webhook es un evento JSON firmado con HMAC-SHA256 sobre la marca de tiempo y el cuerpo sin procesar; tu endpoint verifica la firma del webhook y responde 2xx en menos de 10 segundos. Una entrega fallida se reintenta después de 1 min, 5 min, 15 min, 1 h, 6 h y 24 h, siempre con el mismo event_id, así que tu código guarda el id e ignora las repeticiones. En lugar de webhooks puedes consultar GET /v1/invoices/{id}, como máximo una vez cada pocos segundos. El contrato completo está en la documentación de webhooks.

{
  "event_id": "6f1c2c1e-3b2a-4d5e-8f90-1234567890ab",
  "type": "invoice.paid",
  "created_at": "2023-11-14T22:13:20Z",
  "data": { "invoice": { "id": "0e8c9a4b-1111-4222-8333-444455556666", "status": "paid" } }
}

#Paso 6. El saldo y el retiro

Un pago confirmado de CryptoLike llega a tu saldo de ese activo, menos la comisión de la plataforma: cada fila de GET /v1/transactions muestra el amount bruto, la fee y el net_amount. La comisión de la plataforma se cobra solo cuando un pago se confirma y se acredita; las comisiones vigentes están en la página de precios, con la fecha a la que corresponden.

Los saldos se llevan por activo como available (disponible), pending (pendiente) y hold (retenido). Desde available haces retiros a direcciones externas uno por uno por la API, o en lote desde el panel. Pide antes una estimación: muestra la comisión de la plataforma, la comisión de red reservada y el débito total antes de que confirmes. Las direcciones de retiro se pueden limitar a una lista de direcciones permitidas, y los retiros desde el panel o Telegram por encima de tu umbral pueden requerir una segunda aprobación. Un retiro termina como completed (Completado), o devuelve el dinero a available como failed (Fallido), rejected (Rechazado) o cancelled (Cancelado).

#Estados del pago de un vistazo

Un pago de CryptoLike tiene seis estados, y el mismo valor aparece en la API, en la página de pago y en los webhooks. Tres son finales desde el principio —paid, expired, cancelled— y underpaid se vuelve final cuando vence el plazo; solo un operador de CryptoLike puede reabrir un pago vencido o con pago insuficiente extendiendo su plazo. La tabla relaciona cada estado con el evento que recibe tu servidor y el texto que lee el pagador.

Fuente: el modelo de estados de CryptoLike y el contrato de webhooks, al 2026-09-24.

#¿Y si el pago no sale como se esperaba?

CryptoLike maneja los tres desvíos más comunes sin cambiar el modelo de estados. Un pago insuficiente fuera de la tolerancia pasa a underpaid con remaining_amount y queda abierto para completarse; un pago excedente queda en paid con overpaid_amount; los fondos que llegan después de que el pago se cerró igual se acreditan, con late_payment: true y un evento invoice.late_payment, mientras el estado se mantiene como estaba.

Cada caso tiene un siguiente paso para ti y para el pagador. El artículo sobre pagos cripto insuficientes, excedentes y tardíos los revisa uno por uno. Para un pago vencido la salida es simple: el pago venció, crea un pago nuevo.

#Preguntas frecuentes

#¿Qué diferencia hay entre una pasarela de pagos con criptomonedas y una billetera?

Una billetera guarda claves y envía o recibe transferencias. Una pasarela como CryptoLike crea un pago por un monto fijo y con plazo, le da al pagador una dirección, cuenta las confirmaciones e informa el resultado a tus sistemas mediante el estado y un webhook firmado. Tú no operas un nodo ni guardas claves.

#¿Cuándo debo entregar un pedido?

Entrégalo con paid, que llega junto con invoice.paid. pending solo significa que se vio una transferencia en la red. Si después una reorganización revierte una transferencia confirmada, recibes invoice.reverted; detén la entrega hasta que llegue un nuevo invoice.paid.

#¿Cómo sabe mi servidor que un pago está pagado?

Por un webhook firmado (invoice.paid) o consultando GET /v1/invoices/{id}. Los webhooks se entregan al menos una vez y se reintentan con el mismo event_id, así que verifica la firma, guarda el id e ignora las repeticiones.

#¿Puedo poner el precio de un pago en dólares?

Sí. Pasa un código fiat como USD en currency. El pagador elige el activo en la página de pago entre las monedas disponibles para facturas, el tipo de cambio se fija en ese momento, y el pago guarda el monto fiat, el tipo de cambio fijado y el monto en cripto.

#¿Puedo probar el flujo antes de salir a producción?

Sí. Usa claves de prueba y redes de prueba: las claves con el prefijo ck_test_, junto con la URL de la API de prueba que te da el soporte de CryptoLike, funcionan con las redes de prueba, las monedas de prueba no tienen valor, y el soporte de CryptoLike puede enviarte algunas. El vector de firma de referencia de la documentación de firma de solicitudes te dice en una llamada si firmas bien tus solicitudes.