Pasarelas de criptomonedas: arquitectura, integración y verificación

Qué hace realmente una pasarela de criptomonedas

Una pasarela de criptomonedas es un procesador de pagos para activos digitales. En el checkout, se cotiza al cliente un monto en una moneda o token específico, generalmente derivado de un precio fiat con una ventana de validez corta. La pasarela asigna una dirección de depósito o intención de pago, monitorea la cadena en busca de una transferencia coincidente, aplica umbrales de confirmación y verificaciones de riesgo, y luego acredita el saldo de la pasarela del comerciante o activa la liquidación a una cuenta bancaria o monedero de stablecoin.

El modelo mental importante es que la pasarela no mueve fondos a través de una red de tarjetas. El valor se mueve como transacciones on-chain ordinarias a direcciones que controla la pasarela. Todo lo demás, la factura, el tipo de cambio, el webhook, el asiento contable, es contabilidad superpuesta a esas transferencias. Esa distinción importa porque indica dónde pueden ocurrir fallos: un webhook puede retrasarse o duplicarse mientras la transferencia on-chain es final, y el libro mayor de la pasarela puede estar equivocado mientras la cadena es correcta.

Las pasarelas son opcionales. Un comerciante puede aceptar cripto directamente a una billetera autocustodiada, pero entonces asume la gestión de direcciones, la cotización de precios, la política de confirmación, la contabilidad y los reembolsos. Una pasarela elimina la mayor parte de ese trabajo operativo a cambio de comisiones, términos de custodia o liquidación, y dependencia del tiempo de actividad de un tercero.

• Intención de pago: el registro de factura que vincula un pedido a un monto, activo, dirección y vencimiento.
• Vigilante de cadena: el servicio que escanea bloques en busca de transferencias a direcciones controladas por la pasarela.
• Política de confirmación: cuántos bloques o condiciones de finalidad deben pasar antes de que un pago se considere liquidado.
• Liquidación: conversión y transferencia de valor al comerciante, en cripto o fiat.
• Conciliación: cotejo de los asientos del libro mayor de la pasarela con las transacciones on-chain y sus propios registros de pedidos.

Supuestos y requisitos previos antes de integrar

Esta guía asume que ya tiene un sistema de checkout o pedidos con un componente del lado del servidor, una base de datos donde puede almacenar el estado de los pagos y la capacidad de recibir callbacks HTTPS. Debe saber qué activos y redes pretende aceptar, porque un pago de USDT en una cadena no es la misma integración que USDT en otra: los formatos de dirección, el comportamiento de confirmación y la economía de comisiones difieren.

También necesita una forma de leer datos de la cadena independientemente de la pasarela. Ahí es donde encaja un proveedor de RPC. Una pasarela le dice lo que cree que ocurrió; un endpoint RPC le permite confirmar lo que la cadena registró realmente. Los endpoints RPC multicadena de OnFinality pueden cumplir esa función de verificación, y la lista de redes compatibles le indica qué cadenas están disponibles. Si espera un tráfico de verificación sostenido, revise las opciones de nodos dedicados en lugar de asumir que la capacidad pública compartida es suficiente.

Por último, decida su modelo de liquidación antes de escribir código. La conversión automática custodial a fiat, la liquidación en stablecoin y la liquidación directa en cripto producen formas de libro mayor distintas y pasos de conciliación diferentes.

El flujo de pago desde el checkout hasta la liquidación

Un flujo típico de pasarela tiene seis etapas. Primero, su servidor crea un pago o factura a través de la API de la pasarela, pasando el ID del pedido, el monto, la moneda y la URL de callback. Segundo, la pasarela devuelve un identificador de pago, una dirección de depósito, el monto exacto en cripto, un tipo de cambio y una hora de vencimiento. Tercero, su checkout muestra esa información, a menudo como un código QR más una dirección y un monto copiables.

Cuarto, el cliente difunde una transferencia. Quinto, el vigilante de cadena de la pasarela detecta la transferencia, espera su política de confirmación y marca el pago como confirmado o parcialmente pagado. Sexto, la pasarela envía un webhook firmado a su URL de callback y actualiza su libro mayor. La liquidación hacia usted ocurre según el calendario de la pasarela, que puede ser inmediata por pago, por lotes o a demanda.

Dos detalles causan la mayoría de los errores de integración. El monto cotizado en cripto tiene tiempo limitado, por lo que un pago enviado después del vencimiento puede quedar por debajo del monto según la nueva tasa. Y el monto debe coincidir exactamente después de contabilizar las comisiones de red, que el remitente suele pagar aparte; un cliente que resta las comisiones de la transferencia produce un déficit que la pasarela reportará como parcial.

Creación de una intención de pago a través de la API de la pasarela

El endpoint y los nombres de campo exactos varían según el proveedor, así que trate lo siguiente como una forma y no como una especificación. Confirme siempre con la referencia actual de la API de su proveedor. El patrón es consistente: autentíquese con una clave API mantenida del lado del servidor, cree una factura, persista el identificador y la dirección devueltos, y nunca confíe en montos proporcionados por el cliente.

El ejemplo de curl a continuación utiliza marcadores de posición para la URL base y las credenciales de la pasarela. Ejecútelo desde un entorno de servidor, no desde un navegador, y registre el cuerpo de la respuesta junto con su ID de pedido para poder conciliar más tarde.

curl -X POST "$GATEWAY_BASE_URL/v1/payments" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "order_1042",
    "price_amount": 49.00,
    "price_currency": "USD",
    "pay_currency": "USDT",
    "network": "ETH",
    "callback_url": "https://merchant.example.com/webhooks/gateway",
    "success_url": "https://merchant.example.com/checkout/success"
  }'

Manejo idempotente de webhooks

Los webhooks son el canal de notificación de la pasarela, y no se garantiza que lleguen una sola vez, en orden o en absoluto. Su manejador debe verificar la firma, buscar el pago por el identificador de la pasarela y aplicar una transición de estado solo si hace avanzar el pago. Almacene la carga útil sin procesar y un hash de ella para que las entregas duplicadas sean detectables.

El esquema de JavaScript a continuación muestra la protección esencial: verificar, deduplicar y luego transicionar. Deliberadamente no contiene lógica de firma específica del proveedor, porque eso depende del esquema documentado de la pasarela.

import crypto from "node:crypto";

// Verify signature per your gateway's documented scheme.
function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

async function handleWebhook(req, res) {
  const raw = req.rawBody; // preserve the unparsed body
  if (!verify(raw, req.headers["x-gateway-signature"], process.env.GATEWAY_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const event = JSON.parse(raw);
  const payment = await db.payments.findByGatewayId(event.payment_id);
  if (!payment) return res.status(404).end();

  const seen = await db.webhookEvents.exists(event.event_id);
  if (seen) return res.status(200).end();

  await db.transaction(async (tx) => {
    await tx.webhookEvents.insert({ id: event.event_id, payload: raw });
    if (event.status === "confirmed" && payment.status !== "paid") {
      await tx.payments.markPaid(payment.id, event.txid);
    }
  });
  return res.status(200).end();
}

Verificación de un pago reportado contra la cadena

Un webhook es una afirmación. Antes de enviar productos o liberar fondos por encima de un umbral de riesgo, confirme la afirmación contra un endpoint RPC que usted controle. El procedimiento es: obtener la transacción por hash, verificar que se completó con éxito, verificar que el destinatario coincide con la dirección de depósito, verificar el monto y el activo transferidos, y verificar la profundidad de confirmación.

El ejemplo de Python a continuación utiliza JSON-RPC sobre HTTP con un RPC_URL de marcador de posición. Está escrito para una cadena de estilo EVM y transferencias de valor nativo; las transferencias de tokens requieren decodificar los logs o llamar al evento de transferencia del contrato del token en su lugar. Adapte la verificación del activo a la cadena que acepte.

import os, requests

RPC_URL = os.environ["RPC_URL"]

def rpc(method, params):
    r = requests.post(RPC_URL, json={"jsonrpc":"2.0","id":1,"method":method,"params":params}, timeout=10)
    r.raise_for_status()
    body = r.json()
    if "error" in body:
        raise RuntimeError(body["error"])
    return body["result"]

def verify_payment(tx_hash, expected_to, expected_wei, min_confirmations):
    tx = rpc("eth_getTransactionByHash", [tx_hash])
    receipt = rpc("eth_getTransactionReceipt", [tx_hash])
    if tx is None or receipt is None:
        return {"ok": False, "reason": "not_found"}
    if receipt["status"] != "0x1":
        return {"ok": False, "reason": "reverted"}
    if tx["to"].lower() != expected_to.lower():
        return {"ok": False, "reason": "wrong_recipient"}
    if int(tx["value"], 16) < expected_wei:
        return {"ok": False, "reason": "underpaid"}
    head = int(rpc("eth_blockNumber", []), 16)
    depth = head - int(receipt["blockNumber"], 16) + 1
    return {"ok": depth >= min_confirmations, "depth": depth}

Medición de la latencia de confirmación y el retraso de los webhooks

Los paneles de las pasarelas rara vez publican la latencia que experimentará realmente, porque depende de su cadena, su política de confirmación y las condiciones de la red en ese momento. Mídala usted mismo. Para cada pago de prueba, registre cuatro marcas de tiempo: cuándo se creó la factura, cuándo se vio por primera vez la transacción en un bloque, cuándo la pasarela la marcó como confirmada y cuándo su manejador de webhooks recibió el evento.

Ejecute al menos veinte pagos de prueba por activo y red que planee aceptar, distribuidos en diferentes momentos del día. Calcule la mediana y el percentil 95 para el tiempo de inclusión en la cadena y para el retraso del webhook. No publique ni confíe en cifras del entorno de otro comerciante; los tiempos de bloque y el comportamiento del proveedor cambian.

Registre los resultados en una tabla como la siguiente, completando sus propias mediciones. La estructura de columnas es el entregable; los valores son suyos para producir.

• Columnas: activo, red, umbral de confirmación, tiempo de inclusión mediano, tiempo de inclusión p95, retraso de webhook mediano, retraso de webhook p95, tamaño de muestra.
• Excluya los pagos de prueba que nunca se difundieron o se enviaron con comisiones insuficientes.
• Vuelva a ejecutar la medición después de cualquier cambio de plan de pasarela, actualización de cadena o cambio de política de confirmación.

Solución de problemas comunes de integración

La mayoría de los fallos se engloban en un pequeño conjunto de categorías, y cada una tiene una ruta de diagnóstico. Trabaje desde la cadena hacia afuera: confirme que la transferencia existe, luego confirme que la pasarela la vio, luego confirme que su sistema la registró.

Si el cliente dice que pagó pero la factura muestra pendiente, solicite el hash de la transacción y verifíquelo contra su endpoint RPC. Una transferencia a la dirección incorrecta, una transferencia en la red incorrecta o una transferencia del activo incorrecto no se acreditarán. Si la transacción es correcta y está confirmada pero la pasarela no se ha actualizado, el problema está del lado de la pasarela o en su política de confirmación; consulte su página de estado y su canal de soporte.

Si la pasarela muestra confirmado pero su pedido no está pagado, es probable que el webhook haya fallado la verificación de firma, haya llegado a un endpoint que devolvió un error o se haya descartado. Concilie consultando periódicamente el endpoint de estado de pago de la pasarela para las facturas abiertas, y trate el sondeo como una red de seguridad en lugar de un reemplazo de los webhooks.

• Pago insuficiente: el cliente restó las comisiones de red o envió después de que expirara la cotización.
• Red incorrecta: el mismo símbolo de activo en una cadena diferente, irrecuperable sin el soporte de la pasarela.
• Crédito duplicado: manejador de webhooks no idempotente, o reintentos aplicados dos veces.
• Firma no coincidente: cuerpo sin procesar alterado por el analizador JSON de un framework antes de la verificación.
• Pendiente atascado: umbral de confirmación no alcanzado, o reorganización de la cadena que revirtió el bloque.

Modelos de liquidación y sus compensaciones

La conversión automática custodial liquida cada pago a fiat o a una stablecoin en la pasarela, eliminando la exposición al precio pero añadiendo dependencia de contraparte y regulatoria. La pasarela mantiene los fondos brevemente, aplica su tasa de conversión y paga según un calendario. Su libro mayor registra montos en fiat, y la conciliación compara los extractos de la pasarela con los recibos bancarios o de stablecoin.

La liquidación en stablecoin mantiene el valor en un activo vinculado al dólar on-chain, lo que conviene a las empresas que ya operan en cripto pero aún quieren evitar la volatilidad. La liquidación directa en cripto le paga en el activo recibido, lo que significa que asume el riesgo de precio entre el pago y la conversión y debe gestionar su propia tesorería.

La aceptación autocustodiada, en la que usted genera direcciones y vigila la cadena por sí mismo, ofrece el máximo control y ninguna comisión de pasarela, pero requiere que ejecute o alquile infraestructura confiable, implemente una política de confirmación y gestione los reembolsos manualmente. Es una opción razonable para comerciantes de alto volumen con capacidad de ingeniería; para la mayoría, una pasarela más verificación on-chain independiente es el término medio pragmático.

Limitaciones, cumplimiento y qué verificar antes del lanzamiento

Las pasarelas operan bajo regímenes de licencias que varían según la jurisdicción, y sus activos admitidos, monedas de liquidación y requisitos de KYC difieren en consecuencia. Confirme que su proveedor tiene licencia para servir a las jurisdicciones de sus clientes y a la suya propia, y que sus términos permiten su categoría de negocio. Este artículo no proporciona asesoramiento legal; trate las licencias como una cuestión de adquisición con respuestas documentadas.

Técnicamente, ninguna pasarela elimina el riesgo de la cadena. Las reorganizaciones, el espacio de bloques congestionado y los picos de comisiones afectan el tiempo de confirmación. Sus umbrales de confirmación deben reflejar el valor en riesgo: una pequeña compra digital puede necesitar una confirmación, mientras que una transferencia grande puede justificar un umbral más profundo o una cadena con conciencia de finalidad.

Antes del lanzamiento, verifique cuatro cosas de extremo a extremo: un pago exitoso acredita el pedido exactamente una vez, una transacción fallida o revertida no acredita, un webhook duplicado no acredita dos veces, y existe una ruta de reembolso que su equipo de soporte puede ejecutar. Cada una de estas debe ser una prueba repetible en su entorno de staging.

Próximos pasos para una integración lista para producción

Comience construyendo la capa de verificación junto con la integración de la pasarela en lugar de después. Un pequeño servicio que toma un hash de transacción y devuelve un estado verificado, respaldado por un endpoint RPC que usted controle, le proporciona una fuente independiente de verdad para soporte, conciliación y revisión de fraude. El servicio de API RPC y la cobertura de redes de OnFinality son los puntos de partida; revise los precios de RPC para dimensionar el tráfico de verificación, y considere los nodos dedicados si necesita un rendimiento predecible.

Si aún está eligiendo un endpoint o proveedor para la capa de verificación, la guía del Asistente de RPC sobre endpoints RPC explica las compensaciones, y la guía de endpoints RPC multicadena cubre la operación en varias cadenas. Para equipos que construyen infraestructura Web3 más amplia, la comparación del mejor proveedor de RPC para proyectos Web3 es un complemento útil.

Luego instrumente el flujo: registre cada creación de factura, recepción de webhook y resultado de verificación con un ID de correlación compartido. Ejecute la medición de latencia descrita anteriormente, establezca umbrales de confirmación por activo y programe una conciliación trimestral entre los extractos de la pasarela, los registros on-chain y su propio libro mayor. Esa combinación, una pasarela para la experiencia de pago y sus propias lecturas de cadena para la verdad, es lo que hace que una integración de pasarela de criptomonedas sea auditable.