Integración de la API de Crypto Pay: Construyendo un Flujo de Pago Confiable

Alcance y el modelo mental detrás de una API de crypto pay

Una API de pagos cripto se sitúa entre su sistema de pedidos y la blockchain. Su backend le pide que cree una solicitud de pago por un monto y una moneda conocidos, el cliente envía fondos desde su propia billetera y la API informa cuando se observa una transferencia coincidente. A diferencia de los rieles de tarjetas, las transferencias cripto son pagos push: el cliente inicia el movimiento y no hay emisor que pueda revertirlo. Esa única propiedad explica la mayoría de las diferencias de diseño que encontrará.

El modelo mental útil es un ciclo de vida de cuatro etapas. Crear: su sistema registra una factura con un monto, una referencia y una expiración. Observar: el proveedor vigila direcciones o mempools y hace coincidir las transferencias entrantes con esa factura. Confirmar: la transferencia se cuenta solo después de un número de bloques definido por la política o de una señal de finalidad. Liquidar: su libro mayor marca el pedido como pagado y, opcionalmente, sigue un paso de pago o conversión. Cada error de integración que depure vive en una de estas cuatro etapas.

Este artículo es agnóstico del proveedor. Los nombres de los campos difieren entre pasarelas, pero el ciclo de vida, los requisitos de seguridad y el procedimiento de verificación son estables. Cuando necesite elegir un endpoint o una red específicos, use RPC Assistant en lugar de codificar suposiciones de un tutorial.

• Pagos push: el cliente envía fondos; su sistema nunca los extrae de su billetera.
• Irreversibilidad: los reembolsos son nuevas transacciones salientes, no reversiones.
• Asincronía: la confirmación del pago llega mediante webhook o sondeo, no en la respuesta de creación.
• Variación de finalidad: Bitcoin, Ethereum y las cadenas de finalidad rápida necesitan políticas de confirmación diferentes.

Requisitos previos y supuestos antes de escribir código

Necesita una cuenta de sandbox o testnet con el proveedor de pagos, un par de claves de API (normalmente una clave pública más un secreto usado para firmar), un endpoint HTTPS accesible públicamente para webhooks y un almacén persistente para el estado de las facturas. También necesita una respuesta clara a dos preguntas de política antes de la integración: qué activos y redes aceptará, y cuántas confirmaciones cuentan como liquidadas para cada uno de ellos.

Suponga que su backend es el único componente de confianza. Los clientes de navegador nunca deben contener la clave secreta, y los manejadores de webhooks deben tratar cada solicitud entrante como no confiable hasta que se verifique la firma. Si opera su propia infraestructura de cadena para la verificación, también necesitará un endpoint RPC confiable; la guía de endpoints RPC multicadena cubre cómo estructurar ese acceso, y el servicio de API de OnFinality describe el acceso gestionado si prefiere no ejecutar nodos.

Creación de una factura con una solicitud idempotente

La llamada de creación es el único paso síncrono del flujo y es el que más probablemente reintente su propia infraestructura. Envíe siempre una clave de idempotencia derivada de su ID de pedido interno para que un tiempo de espera de red no produzca dos facturas para un mismo pedido. El ejemplo siguiente usa credenciales de marcador de posición y una forma REST genérica; adapte los nombres de los campos a la referencia de su proveedor.

curl -X POST "$PAY_API_BASE/v1/invoices" \
  -H "Authorization: Bearer $PAY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.00",
    "currency": "USD",
    "asset": "USDT",
    "network": "ethereum",
    "reference": "order-10482",
    "expires_in": 900,
    "callback_url": "https://api.example.com/webhooks/pay"
  }'

Manejo del webhook: verifique antes de confiar

Los payloads de webhook son la señal principal de que llegaron los fondos, pero también son la fuente más común de fraudes y errores de doble abono. Verifique la firma contra el cuerpo sin procesar de la solicitud, no contra un objeto analizado y reserializado, porque la reserialización cambia el orden de los bytes y rompe las comprobaciones HMAC. Luego verifique el ID del evento contra un almacén de deduplicación antes de aplicar cualquier cambio de estado.

El manejador siguiente muestra el patrón en Node.js: lea el cuerpo sin procesar, calcule un HMAC con el secreto compartido, compare en tiempo constante, deduplique y luego realice la transición del pedido. El nombre exacto del encabezado y el esquema de firma varían según el proveedor; sustituya los suyos.

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const seen = new Set(); // replace with a durable store

app.post('/webhooks/pay', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-Pay-Signature') || '';
  const expected = crypto
    .createHmac('sha256', process.env.PAY_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  const ok = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!ok) return res.status(401).send('bad signature');

  const event = JSON.parse(req.body.toString('utf8'));
  if (seen.has(event.id)) return res.status(200).send('duplicate');
  seen.add(event.id);

  // Only act on the terminal state, not intermediate ones.
  if (event.type === 'payment.confirmed') {
    // enqueue order transition; do not do heavy work inline
  }
  res.status(200).send('ok');
});

Política de confirmación y el procedimiento de verificación

Un pago no se liquida cuando la transferencia aparece en la mempool; se liquida cuando su política lo indica. Defina un umbral de confirmación por red y regístrelo con cada factura para que luego pueda auditar por qué se marcó un pedido como pagado. Para cadenas de finalidad rápida, el umbral puede ser una señal de gadget de finalidad en lugar de un conteo de bloques; para cadenas de prueba de trabajo, es una profundidad.

Para verificar su integración de extremo a extremo, ejecute este procedimiento en un sandbox y registre los valores observados en una tabla. No copie números de ninguna guía, incluida esta; mida los suyos.

• Cree una factura y confirme que la respuesta contiene un ID único y una dirección o URI de pago.
• Envíe una transferencia de prueba por debajo del monto de la factura y confirme que la API informa un estado de pago insuficiente, no pagado.
• Envíe el monto restante y confirme que el estado pasa a pendiente y luego a confirmado después de su umbral.
• Repita el mismo webhook dos veces y confirme que su manejador abona el pedido exactamente una vez.
• Deje expirar una factura impaga y confirme que las transferencias tardías se marcan para revisión manual en lugar de abonarse automáticamente.

Conciliación del libro mayor del proveedor con el suyo

Los webhooks pueden perderse, retrasarse o entregarse fuera de orden. Un trabajo de conciliación programado que enumera las facturas en una ventana de tiempo y las compara con su tabla de pedidos es la red de seguridad. Trate al proveedor como la fuente de verdad para la observación en cadena y a su base de datos como la fuente de verdad para el cumplimiento; el propósito del trabajo es encontrar y reparar divergencias.

El esbozo en Python siguiente obtiene las facturas recientes y marca cualquiera que esté confirmada en el proveedor pero no cumplida localmente. Ejecútelo según una programación y alerte cuando la salida no esté vacía en lugar de cumplir automáticamente en silencio.

import os, requests

base = os.environ["PAY_API_BASE"]
headers = {"Authorization": f"Bearer {os.environ['PAY_API_KEY']}"}

resp = requests.get(f"{base}/v1/invoices", headers=headers,
                    params={"status": "confirmed", "limit": 100}, timeout=15)
resp.raise_for_status()

for inv in resp.json().get("data", []):
    if not local_order_is_fulfilled(inv["reference"]):
        print("DIVERGENCE", inv["id"], inv["reference"], inv["amount"])

Solución de problemas que realmente ocurren

La mayoría de los incidentes en producción caen en un pequeño conjunto de patrones. Los fallos de firma suelen significar que el cuerpo se analizó antes de la verificación o que el secreto pertenece a un entorno diferente. Los abonos duplicados suelen significar que el almacén de deduplicación está en memoria y se reinicia al desplegar. Las facturas pendientes atascadas suelen significar que el cliente envió en una red diferente a la especificada en la factura, o que el monto quedó por debajo del umbral de polvo del proveedor.

Los pagos insuficientes y excesivos merecen un manejo explícito. Decida de antemano si se acepta un pago insuficiente dentro de una tolerancia y si un pago excesivo se reembolsa o se abona. Las transferencias tardías después de la expiración deben dirigirse a revisión manual, nunca a cumplimiento automático. Si sus propias lecturas de cadena forman parte del flujo, los errores intermitentes de RPC pueden parecer pagos faltantes; la guía de endpoints RPC explica los patrones de reintento y conmutación por error que evitan ese tipo de falso negativo.

• 401 en el webhook: cuerpo sin procesar no preservado, o secreto de entorno incorrecto.
• Pedido abonado dos veces: deduplicación basada en el hash del payload en lugar del ID del evento, o almacén no duradero.
• Factura que nunca se confirma: red incorrecta seleccionada por el cliente, o monto por debajo del umbral.
• Ruido de conciliación: desajuste de zona horaria entre las marcas de tiempo del proveedor y su consulta de ventana.

Pasarela alojada versus infraestructura de nodos autogestionada

Una API de pagos cripto alojada le ofrece gestión de facturas, derivación de direcciones, seguimiento de confirmaciones y, a menudo, conversión o pago en un solo contrato. Intercambia control y costo por transacción por velocidad de integración y riesgo operativo externalizado. Un enfoque autogestionado, en el que ejecuta nodos y vigila direcciones usted mismo, le da custodia total de la capa de observación y ninguna dependencia de terceros para la lógica de confirmación, pero usted asume el tiempo de actividad, el manejo de reorganizaciones y las peculiaridades de cada cadena.

La decisión suele depender de cuántas redes soporta y de cuánta lógica de liquidación es central para su producto. Si los pagos son una característica, una pasarela suele ser lo correcto. Si la observación de pagos es el producto, la infraestructura autogestionada con una capa RPC confiable vale el costo. Para los equipos que optan por la ruta autogestionada, la capacidad de nodo dedicado elimina los efectos de vecino ruidoso que causan bloques perdidos, y los precios de RPC ayudan a modelar el costo por red antes de comprometerse.

Limitaciones y compensaciones que aceptar desde el principio

Ninguna integración elimina el riesgo de finalidad de la blockchain; solo desplaza dónde lo mide. Los umbrales de confirmación intercambian latencia por seguridad, y el valor correcto depende del tamaño de la transacción, no solo de la cadena. La entrega de webhooks es al menos una vez en la mayoría de los sistemas, por lo que la idempotencia es obligatoria y no opcional. La conversión de moneda, si se ofrece, introduce una tasa en un momento dado que debe almacenarse con la factura para la resolución de disputas.

También hay una superficie de cumplimiento que la ingeniería no puede eliminar por diseño: las obligaciones de conocimiento del cliente, la selección de sanciones y la retención de registros varían según la jurisdicción y según si usted custodia fondos. Trátelas como requisitos de producto que limitan qué proveedores y redes puede aceptar, no como algo secundario.

Próximos pasos para un flujo listo para producción

Pase del sandbox a producción por etapas: habilite un activo en una red, ejecute el procedimiento de verificación con transacciones reales de bajo valor y observe la salida de conciliación durante una semana antes de expandirse. Añada alertas sobre fallos de firma de webhooks, divergencias de conciliación y facturas atascadas en pendiente más allá de su tiempo de confirmación esperado. Documente su política de confirmación por red para que el personal de soporte pueda explicar por qué un pedido aún no se ha cumplido.

Cuando necesite elegir endpoints concretos o confirmar qué redes soporta un proveedor, pregunte a RPC Assistant para obtener una recomendación directa en lugar de inferirla de páginas de marketing. Para obtener información sobre la infraestructura subyacente, la guía de alojamiento de nodos blockchain y el directorio de redes son puntos de partida útiles.