API de pasarela de pago cripto: 12 puntos a revisar antes de integrarla

Toda API de pasarela de pago cripto promete lo mismo: crear una factura, cobrar y recibir un callback. Las diferencias aparecen después: cuando dos peticiones compiten entre sí, cuando un cliente envía un poco menos de lo facturado, cuando tu servidor se cae una hora o cuando un atacante reenvía una petición capturada. Elegir la API con cuidado ahorra mucho más tiempo que integrarla deprisa.

Esta es una checklist para desarrolladores y CTO que comparan APIs de pagos cripto antes de escribir una sola línea de código. En cada punto verás qué buscar, por qué importa y cómo lo resuelve la API de mistKET. Si ya has elegido y quieres el código paso a paso, ve directamente a nuestra guía de integración de API de pagos cripto.

Los endpoints mínimos

Una API de pagos cripto útil necesita algo más que «crear pago». Como mínimo, busca esto:

Si un proveedor no permite consultar ni listar facturas, te obliga a confiar ciegamente en los webhooks: una mala posición en cuanto falle la primera entrega.

1. Autenticación: ¿va firmada cada petición?

Una API key enviada en una cabecera es la opción más débil: cualquiera que la intercepte o la filtre puede crear y cancelar facturas. Prefiere una API en la que cada petición se firme con un secreto que nunca viaja por la red. Las peticiones a mistKET llevan X-Api-Key, X-Api-Timestamp y una firma HMAC-SHA256 del timestamp y el cuerpo en bruto. El secreto se muestra una sola vez en el panel del comercio.

2. Protección contra replay

Una firma por sí sola no impide que alguien reenvíe una petición capturada. Busca una ventana de timestamp y soporte de nonce. mistKET rechaza timestamps que se desvíen más de ±300 segundos de la hora del servidor y no acepta dos veces la misma firma en peticiones que cambian estado. Su versión 2 de firma añade un nonce por petición y firma también el método y la ruta, de modo que una firma no se puede reutilizar en otro endpoint.

3. Idempotencia al crear facturas

Las redes sufren timeouts. Si tu checkout reintenta una llamada de «crear factura», no puedes acabar con dos facturas para un mismo pedido. Una buena API ofrece una clave de idempotencia. En mistKET ese papel lo cumple tu propio order_id: si llamas de nuevo con el mismo ID de pedido, recibes la factura existente con "idempotent": true en lugar de una nueva.

4. Un modelo de estados que cubra pagos reales

«Pagado / no pagado» no basta. Los clientes envían un poco menos porque un exchange descontó una comisión, o de más, o pagan tras la caducidad. Comprueba que la API expone estos casos de forma explícita. Las facturas de mistKET pasan por new, pending, underpaid, paid, confirmed, overpaid, expired y cancelled, con campos como paid_amount, remaining_amount, can_pay_remaining y under_review para que tu código nunca tenga que adivinar.

5. Confirmaciones visibles

La API debería decirte cuántas confirmaciones de bloque tiene un pago y cuántas se requieren, además del hash de la transacción y un enlace al explorador. Así los tickets de soporte sobre pagos se resuelven con una consulta rápida. mistKET devuelve para cada factura confirmations, required_confirmations y un array transactions[] con hash, importe, estado y URL del explorador.

6. Bloqueo del tipo de cambio y monedas de precio

Tú pones el precio en fiat; el cliente paga en cripto. Pregunta qué monedas fiat se aceptan y durante cuánto tiempo se mantiene la cotización. mistKET acepta precios en USD, EUR, TRY, RUB, GBP y AED (o directamente en el símbolo cripto), bloquea el tipo de cambio durante la vida de la factura y te permite fijar esa duración entre 5 y 1.440 minutos por factura.

7. Selección de red

¿Puedes fijar la red en la llamada a la API o dejar que el cliente la elija en la página alojada? Ambas opciones son útiles: fijarla encaja con bots y flujos automatizados, y dejar elegir al cliente reduce los pagos por la red equivocada. mistKET admite las dos mediante pay_currency + network o asset_id, y GET /assets devuelve available: false cuando una red no tiene direcciones libres. Hoy está habilitado USDT en TRON (TRC-20); otros activos y redes se habilitan por comercio bajo solicitud. En USDT TRC20 vs ERC20 explicamos por qué TRON es la opción habitual por defecto.

8. Webhooks firmados, con reintentos y trazables

Los webhooks son donde fallan la mayoría de integraciones. Comprueba cuatro cosas: que el payload va firmado, que hay un timestamp para rechazar entregas obsoletas, que las entregas fallidas se reintentan durante horas (no segundos) y que cada entrega tiene un ID para deduplicar. mistKET firma los webhooks con un secreto de webhook independiente, envía las cabeceras X-Mistket-Delivery y X-Mistket-Event y reintenta las respuestas que no son 2xx a los 10 s, 30 s, 2 min, 10 min, 30 min, 1 h, 2 h y 3 h, con el historial de entregas visible en el panel. Nuestro artículo sobre webhooks de pagos cripto profundiza en el diseño del handler.

9. Errores y límites de peticiones documentados

Deberías saber de antemano cómo es una firma incorrecta, una IP bloqueada o un error de validación. mistKET devuelve un cuerpo { "success": false, "error": … } uniforme con detalles por campo en los errores de validación, usa códigos estándar (401, 403, 404, 422, 429, 503) y documenta su límite: 120 peticiones por minuto por API key.

10. Controles a nivel de red

Con una lista de IP permitidas, una clave filtrada no sirve de nada fuera de tus servidores. mistKET te permite configurarla en el panel; las peticiones desde otras direcciones reciben 403. Junto con las peticiones firmadas y las ventanas de timestamp cortas, esto cierra las vías de ataque más comunes.

11. Sin dependencia de un SDK

Los SDK son cómodos hasta que se quedan atrás respecto a la versión de tu lenguaje. Una API basada en HTTPS y JSON simples, en la que firmar es una sola llamada HMAC, funciona desde PHP, Node.js, Python, Go o un script de shell. mistKET publica clientes listos para copiar y pegar en PHP, Node.js y Python en su documentación de la API, pero ninguno es obligatorio.

12. Una vía manual para quien no programa

Incluso los negocios API-first necesitan facturar alguna vez a un cliente puntual. Comprueba que las facturas también se pueden crear desde un panel y compartir como enlace, para que ventas y soporte no tengan que recurrir a los desarrolladores. En mistKET, las mismas facturas están disponibles en el panel del comercio y cada página de checkout alojado funciona como enlace de pago.

Señales de alarma al evaluar una API de pagos cripto

• Webhooks sin firmar o «protegidos» solo por una URL secreta.
• No poder consultar una factura después de crearla.
• Sin estado de pago insuficiente o excedente: los casos límite acaban en el chat de soporte.
• Reintentos durante solo unos minutos o sin registro de entregas.
• Límites de peticiones y formatos de error sin documentar.
• Precio por transacción poco claro: compáralo con nuestra guía de comisiones de las pasarelas de pago cripto.

Cómo obtener acceso a la API de mistKET

El equipo de mistKET da de alta a los comercios: escribe a @mistnetwork en Telegram con tu web, el tipo de negocio y el volumen previsto. Una vez aprobado, creas tu API key, tu secreto y la configuración de webhooks en el panel del comercio. Una integración típica lleva una tarde.

Revisa la sección para desarrolladores, los precios y la referencia completa de la API antes de empezar.