API de pasarela de pago cripto: facturas, webhooks, pagos salientes y marca blanca

¿Qué hace la API de una pasarela de pago cripto?

La API oculta la blockchain a su código. En lugar de ejecutar nodos, derivar direcciones y contar confirmaciones, usted llama a un endpoint para crear una factura, guarda el identificador de la pasarela y espera notificaciones. La pasarela cotiza el tipo de cambio, vigila las redes, aplica el cribado AML y liquida en su saldo.

La mayoría de las pasarelas ofrece los mismos bloques con nombres distintos: facturas u órdenes para los cobros, IPN o callbacks para las notificaciones, endpoints de conversión y de saldo, y pagos salientes o retiradas para las transferencias de salida. Casi todos los proveedores tienen sandbox, por ejemplo un host de sandbox aparte en CoinGate y una cuenta de sandbox en NOWPayments, y conviene usarlo antes de cualquier prueba en la red principal.

• API de facturas: crear, consultar y cancelar solicitudes de pago con precio en fiat, monedas aceptadas, referencia del pedido y URL de callback
• Notificaciones: webhooks o IPN en cada cambio de estado, normalmente firmados
• API de pagos salientes: enviar cripto o fiat a clientes, socios o a su propia cartera
• Tipos y monedas: listar monedas, redes e importes mínimos admitidos y obtener cotizaciones en vivo
• Plugins y SDK: módulos listos para plataformas de comercio electrónico sobre la misma API

¿Cómo funciona el ciclo de vida de una factura?

Cada pasarela tiene su propio modelo de estados, así que tradúzcalos a un conjunto interno pequeño antes de escribir la lógica de negocio. Solo un estado final de pagado debe liberar el producto; los estados intermedios existen porque una transacción puede verse en la cadena mucho antes de ser segura.

La tabla relaciona dos modelos de estados publicados con los estados que necesitan la mayoría de las plataformas. CoinGate, por ejemplo, hace caducar una factura sin pagar a los 20 minutos de que el cliente elija moneda y marca como inválidos los pagos señalados por los controles AML.

¿Cómo se verifican los webhooks e IPN de cripto?

Trate cada notificación como no fiable hasta verificarla. Las pasarelas usan esquemas distintos: NOWPayments firma el cuerpo JSON ordenado con HMAC-SHA512 y lo envía en la cabecera x-nowpayments-sig, CoinGate envía un token que usted define en la orden, y BitPay recomienda consultar la factura en la API tras cada notificación en lugar de fiarse de su cuerpo.

El patrón más seguro combina ambos: verificar la firma, leer después la factura desde la API y actuar según esa respuesta. Cuesta una petición por cambio de estado y le protege de callbacks falsificados o repetidos.

• Verifique las firmas con una comparación en tiempo constante y rechace las peticiones sin firmar
• Vuelva a consultar la factura por su ID de pasarela antes de cambiar el estado del pedido
• Responda HTTP 200 enseguida y procese de forma asíncrona; las pasarelas reintentan si hay errores
• Guarde cada notificación con su evento o estado para ignorar los duplicados
• No confíe nunca en importes ni monedas enviados en la redirección del navegador

¿Cómo tratar pagos de menos, pagos de más y pagos tardíos?

Las carteras y los exchanges descuentan comisiones de retirada y los clientes copian mal los importes, así que no puede darse por hecho un pago exacto. Defina antes del lanzamiento una tolerancia y una regla para cada caso, y haga visible el resultado para el equipo de soporte.

¿Cómo funcionan la idempotencia y la conciliación?

Cree las facturas con su propia referencia de pedido y haga que la llamada sea segura de repetir: si la petición agota el tiempo de espera, busque la factura por referencia antes de crear otra, o use una clave de idempotencia si la pasarela la admite. La misma regla vale para los pagos salientes, donde una petición duplicada envía dinero real dos veces.

Para conciliar, guarde el ID de factura de la pasarela, el hash de la transacción, el importe en fiat, el importe en cripto, el tipo de cambio y la comisión. Los informes de liquidación muestran los pagos salientes por lotes, de modo que la correspondencia va del pedido a la factura y al pago, y no del pedido a la línea bancaria.

¿Qué exige una API de pagos salientes por la Travel Rule?

Los endpoints de pagos salientes envían cripto desde el saldo de su pasarela a una dirección, a menudo por lotes para comisiones de afiliados, vendedores de un marketplace o retiradas de clientes. La mayoría exige una lista blanca de direcciones, aprobación en dos factores o una clave de API con permisos de pago separados.

En la UE, el Reglamento (UE) 2023/1113 obliga a la pasarela a transmitir los datos del ordenante y del beneficiario con cada transferencia y a verificar la titularidad de las carteras propias por encima de 1.000 EUR. Cuente con que las solicitudes de pago incluyan el nombre del beneficiario y el tipo de dirección, y prevea transferencias que esperan estos datos.

¿Qué opciones de pasarela de pago cripto en marca blanca existen?

Las plataformas que revenden pagos a sus propios comercios suelen querer la página de pago con su marca. Hay tres niveles y el precio sube con el control. Plisio, por ejemplo, anuncia un 0,5 % para su API y un 1,5 % para marca blanca, y NOWPayments vende un producto de marca blanca aparte.

La marca blanca completa traslada responsabilidad además de imagen. Si da de alta comercios y custodia sus saldos, puede necesitar su propia autorización MiCA; usar el modelo de submerchants de una pasarela autorizada mantiene esa obligación en la pasarela.

¿Cómo conectar las API de pasarelas cripto con OrsunPay?

OrsunPay unifica estados, webhooks y reembolsos de las pasarelas cripto en una sola API junto a sus proveedores de tarjeta y banca, con sus propias cuentas de pasarela. No custodia cripto ni ejecuta pagos salientes desde un saldo propio; enruta las peticiones a la pasarela que usted elija y devuelve eventos firmados y sin duplicados.

Cómo integrar la API de una pasarela de pago de criptomonedas

1. Abra cuentas de sandbox Cree cuentas de sandbox y de producción en la pasarela, genere claves de API distintas para facturas y pagos salientes y defina el secreto de IPN.
2. Asigne los estados Traduzca los estados de la pasarela a sus estados internos y decida cuál libera el producto.
3. Cree las facturas de forma idempotente Envíe importe fiat, moneda, referencia del pedido y URL de callback; busque por referencia antes de reintentar una llamada que agotó el tiempo.
4. Verifique las notificaciones Compruebe la firma, vuelva a consultar la factura en la API y procese el evento una sola vez.
5. Gestione los casos límite Implemente tolerancia, complemento, reembolso y caducidad, y pruebe cada caso en el sandbox.
6. Concilie las liquidaciones Guarde el hash de la transacción, el tipo de cambio y la comisión de cada factura y relacione a diario los lotes de pagos con los pedidos.