Crypto Payment Gateway API: Guía Completa de Integración para 2026

Una crypto payment gateway API es la interfaz programática que permite a tu aplicación crear solicitudes de pago, monitorear confirmaciones de transacciones en cadena y liquidar fondos, sin gestionar directamente wallets ni claves privadas. Llamas a un endpoint REST, el gateway gestiona la capa blockchain, y tu backend recibe un webhook cuando el pago llega.

Esto es diferente a un procesador de pagos (que gestiona autorizaciones fiat) o una wallet de autocustodia (donde los usuarios firman transacciones ellos mismos). La API está en el medio: tu app controla la experiencia de usuario, el gateway gestiona las confirmaciones, verificaciones de cumplimiento y la conversión opcional a fiat.

En el ciclo de pago, el crypto payment gateway hace cuatro cosas: genera una dirección de depósito o URL de pago, monitorea la blockchain para fondos entrantes, dispara un webhook cuando se alcanzan los umbrales de confirmación, y opcionalmente convierte el importe recibido. Tu integración solo necesita gestionar los pasos 1 y 3.

El flujo completo de pago tiene cinco pasos.

Paso 1 — Crear una intención de pago

Tu servidor llama a `POST /payments` con el importe esperado, la moneda y un `orderId` que generas tú. El gateway devuelve un `paymentId`, una dirección de depósito y una marca de tiempo de expiración.

Paso 2 — Redirección o visualización

En checkouts alojados, redirige al usuario a la URL del gateway. En integraciones directas, muestra la dirección de depósito y el QR en tu propia UI.

Paso 3 — Recibir el callback del webhook

Cuando el gateway detecta una transacción entrante, envía una solicitud POST a tu URL de webhook. El payload incluye `paymentId`, estado actual, confirmaciones y el importe recibido.

Paso 4 — Verificar y confirmar

Antes de hacer cualquier cosa con el webhook, verifica la firma HMAC en los headers. Si no coincide, rechaza la solicitud. Luego llama a `GET /payments/{id}` para verificar el estado canónico en el servidor.

Paso 5 — Completar el pedido

Una vez que el estado del servidor sea `completed`, completa el pedido de forma idempotente usando `paymentId` como clave de idempotencia. Los webhooks pueden dispararse más de una vez para el mismo evento.

La configuración del crypto payment gateway controla si la liquidación es síncrona o asíncrona.

Una API de payment gateway bien diseñada expone cuatro grupos de endpoints principales.

Creación de intención de pago — POST /payments

Una solicitud mínima se ve así:

```json

{

"orderId": "ord_abc123",

"amount": "250.00",

"currency": "USD",

"payCurrency": "ETH",

"callbackUrl": "https://yourapp.com/webhooks/payments",

"successUrl": "https://yourapp.com/orders/ord_abc123/success",

"expiresIn": 1800

}

```

La respuesta incluye `paymentId`, `depositAddress`, `expectedAmount` en cripto y `expiresAt`.

Estado de transacción — GET /payments/{id}

Usa este endpoint para confirmar el estado después de recibir un webhook.

Reembolsos — POST /refunds

Pasa el `paymentId` y `amount`. El gateway inicia una transferencia on-chain de vuelta a la dirección del remitente.

Informes de liquidación — GET /settlements

Consulta liquidaciones por rango de fechas para la conciliación.

Los webhooks superan al polling por una razón: te enteras de las confirmaciones en cuanto ocurren.

Por qué los webhooks superan al polling

El polling genera llamadas API innecesarias y añade latencia. Los webhooks envían eventos en el momento en que se alcanzan los umbrales de confirmación.

Verificación de firma HMAC-SHA256

```javascript

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {

const expectedSig = crypto

.createHmac('sha256', secret)

.update(rawBody, 'utf8')

.digest('hex');

const expected = Buffer.from(expectedSig, 'hex');

const received = Buffer.from(signature, 'hex');

if (expected.length !== received.length) return false;

return crypto.timingSafeEqual(expected, received);

}

app.post('/webhooks/payments', express.raw({ type: 'application/json' }), (req, res) => {

const sig = req.headers['x-signature'];

if (!verifyWebhookSignature(req.body, sig, process.env.WEBHOOK_SECRET)) {

return res.status(401).json({ error: 'Invalid signature' });

}

const event = JSON.parse(req.body);

res.json({ received: true });

});

```

Pasa el body de la solicitud en crudo (Buffer), no el JSON parseado.

Reintento con retroceso exponencial

Los gateways reintentan webhooks fallidos con retroceso exponencial: típicamente 3-5 veces.

Claves de idempotencia

Usa `paymentId` como clave de idempotencia para evitar pedidos duplicados.

La mayoría de los gateways importantes incluyen SDKs para TypeScript/Node, Python, Go y PHP.

Usa el SDK cuando:

• •Tu stack coincide con un lenguaje soportado
• •Necesitas seguridad de tipos en los objetos de solicitud/respuesta
• •Quieres lógica de reintento ya incorporada

Usa REST puro cuando:

• •Tu stack no está soportado (Rust, Elixir)
• •Necesitas control preciso sobre el comportamiento HTTP
• •La versión del SDK está detrás de la versión de la API

Para la mayoría de los equipos, el SDK es la elección correcta. Aprende más sobre lo que las blockchain APIs para desarrolladores hacen bajo el capó.

Una guía de integración realista en cinco pasos.

Paso 1: Elegir un proveedor de Payment Gateway API

Evalúa cinco criterios: cadenas soportadas, estructura de tarifas, calidad del sandbox, profundidad de la documentación y preparación para el cumplimiento normativo.

Para empresas con requisitos DeFi, también verifica la compatibilidad con plataformas DeFi.

Paso 2: Obtener claves API y acceso al Sandbox

Tu conjunto de claves API tiene dos componentes: clave pública (en headers de solicitud) y clave secreta (para firma HMAC). Almacena ambas en variables de entorno.

Paso 3: Crear tu primera intención de pago

```javascript

const axios = require('axios');

async function createPayment(orderId, amountUSD) {

const response = await axios.post(

'https://api.yourgateway.com/v1/payments',

{

orderId,

amount: amountUSD.toString(),

currency: 'USD',

payCurrency: 'USDT_ETH',

callbackUrl: process.env.WEBHOOK_URL,

expiresIn: 3600,

},

{

headers: {

Authorization: `Bearer ${process.env.GATEWAY_API_KEY}`,

'Idempotency-Key': orderId,

'Content-Type': 'application/json',

},

}

);

return response.data;

}

```

Paso 4: Gestionar callbacks de webhook

Configura tu endpoint de webhook antes de probar. En el sandbox, la mayoría de los gateways permiten disparar eventos de webhook manualmente.

Paso 5: Verificar y completar el pedido

Tras recibir un webhook `completed`, siempre haz una verificación del lado del servidor (`GET /payments/{id}`). Luego completa el pedido y márcalo como procesado con `paymentId` como clave de idempotencia.

La seguridad no es una preocupación post-lanzamiento. Estos requisitos pertenecen a la fase de decisiones arquitectónicas.

Seguridad del transporte

TLS 1.3 como mínimo para toda la comunicación API.

Gestión de claves API

Rota las claves API trimestralmente. Usa pares de claves separados para sandbox y producción.

Cumplimiento KYC/AML

Para empresas que procesan por encima de ciertos umbrales, se aplican las directrices FATF sobre AML. Los estándares PCI DSS aplican técnicamente a los flujos de pago cripto.

Solicitudes firmadas

Algunos proveedores requieren solicitudes API firmadas (similar a AWS Signature V4). Para empresas que desarrollan soluciones fintech completas, una revisión de arquitectura de seguridad API antes del lanzamiento es imprescindible.

Así se comparan los principales proveedores en las dimensiones que realmente importan para las decisiones de integración.

Estos son los errores que los equipos cometen en producción, no en tutoriales.

Umbrales de confirmación incorrectos

Bitcoin necesita 6 confirmaciones para transacciones de alto valor: aproximadamente 60 minutos. Usar 1 confirmación te expone a ataques de doble gasto. Establece umbrales según el valor: 1 para <$100, 3 para $100-$1000, 6 para >$1000 en Bitcoin mainnet.

Gestión de timeouts on-chain

Las transacciones cripto pueden permanecer sin confirmar durante horas. Mantén activo el estado `watchAddress` durante 24-72 horas tras la expiración de la intención de pago.

Errores de estimación de gas

Para cadenas EVM, añade un buffer de tolerancia del 5-10% en pagos denominados en ETH, o cambia a stablecoins USDT/USDC.

Consulta más detalles sobre costes en el artículo sobre desarrollo de crypto payment gateway.