# Cómo funciona una pasarela de pagos con criptomonedas

> Del pago creado al retiro: página de pago, detección de la transferencia, confirmaciones, webhook firmado y saldo. Cada paso de un pago cripto en CryptoLike.

Source: https://cryptolike.net/es/blog/how-crypto-payment-gateway-works
Published: 2026-09-25 · Updated: 2026-10-04 · Author: CryptoLike team

Puntos clave:

- Un pago cripto pasa por new, pending y paid; underpaid, expired y cancelled cubren los demás desenlaces.
- La página de pago muestra el monto, la red, la dirección y el tiempo restante antes de que el pagador envíe nada.
- El estado paid (Pagado) significa que la transferencia alcanzó el umbral de confirmaciones del activo y que los fondos están en tu saldo.
- Tu servidor conoce el resultado por un webhook firmado o con GET /v1/invoices/{id}; después entregas el pedido y haces retiros desde el mismo saldo.

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](https://cryptolike.net/es/guides/accept-crypto-payments).

## ¿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](https://cryptolike.net/es/use-cases/online-stores) conecta un plugin, un [servicio de bienes digitales o SaaS](https://cryptolike.net/use-cases/digital-goods) llama a la API, y un servicio con saldos de usuarios le da a cada usuario una [dirección de depósito estática](https://cryptolike.net/es/use-cases/deposits). 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](https://cryptolike.net/es/blog/choose-crypto-payment-gateway).

## 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](https://cryptolike.net/glossary/payment-link) desde el panel o el bot de Telegram, o una [factura cripto](https://cryptolike.net/es/glossary/crypto-invoice) 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](https://cryptolike.net/docs/widget).

## 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](https://cryptolike.net/blog/crypto-payment-confirmations) explica por qué los umbrales varían entre redes; el [catálogo de monedas](https://cryptolike.net/es/coins) 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](https://cryptolike.net/es/glossary/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](https://cryptolike.net/es/glossary/webhook-signature) 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](https://cryptolike.net/docs/webhooks).

```json
{
  "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](https://cryptolike.net/es/pricing), 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](https://cryptolike.net/glossary/payout-whitelist), 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.

| Estado | Significado | Webhook | Lo que ve el pagador | Final |
|---|---|---|---|---|
| `new` | Creado; no se recibió nada | `invoice.created` | «Esperando el pago. Envía exactamente 49.90 USDT a la dirección de abajo.» | no |
| `pending` | Se detectó una transferencia; esperando confirmaciones | `invoice.pending` | «Pago detectado. Esperando confirmación.» | no |
| `paid` | El monto se confirmó, dentro de la tolerancia de pago insuficiente, y se acreditó | `invoice.paid` | «Pago confirmado.» | sí |
| `underpaid` | Se confirmó menos del monto, fuera de la tolerancia; abierto para completar el pago en la misma dirección hasta el plazo límite | `invoice.underpaid` | «Pago insuficiente: se recibieron 40 de 49.90 USDT. Envía los 9.90 USDT restantes a la misma dirección.» | al vencer el plazo |
| `expired` | Venció el plazo sin nada confirmado | `invoice.expired` | «El pago venció. Crea un pago nuevo.» | sí |
| `cancelled` | Lo cancelaste; solo es posible desde `new` | `invoice.cancelled` | «El comercio canceló el pago. Si aún quieres pagar, pide al comercio un pago nuevo.» | sí |

Fuente: el [modelo de estados](https://cryptolike.net/docs#status-model) 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](https://cryptolike.net/blog/underpaid-crypto-payments) 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](https://cryptolike.net/docs/auth) te dice en una llamada si firmas bien tus solicitudes.