Integración de pagos cripto en el backend, paso a paso
Integración de pagos cripto en el backend paso a paso: crea pagos desde tu servidor, redirige al cliente, verifica webhooks y concilia pedidos.
Integrar pagos cripto en un backend requiere tres piezas: una llamada del servidor que crea el pago, una redirección para el cliente y un webhook que cierra el pedido. Esta guía recorre cada paso con la API v1 de Qvard.
Paso 1: guarda primero el pedido
Guarda el pedido en tu base de datos con un estado como pending antes de llamar a la API. Usa el id de tu pedido como campo id, así el pago y el pedido quedan vinculados desde el principio.
Paso 2: crea el pago
Desde tu backend envía POST /api/v1/payment con la cabecera x-api-key, el id del pedido en id y el total en price. Guarda la clave de API en la configuración del servidor y nunca en el código del frontend.
Paso 3: redirige al cliente
Guarda el redirectUrl devuelto junto al pedido y envía allí al cliente. En la página alojada el cliente elige activo y red y paga el importe exacto.
x-api-key: sk_live_…
{
"id": "order_1024",
"price": 12499.00,
"currency": "INR",
"paymentSystemId": 12
}
// 201 Created
{
"data": {
"id": "8f3k2a1c",
"redirectUrl": "https://my.qvard.com/pay/8f3k2a1c"
},
"code": 201,
"message": "success",
"status": true
}Paso 4: cierra el pedido desde el webhook
Tu endpoint de webhook comprueba x-api-key, busca el pedido por id y lo marca como pagado cuando el estado es paid. Es el único lugar donde se confirma un pago.
Paso 5: concilia y monitoriza
Ejecuta cada día una comprobación de los pedidos que llevan demasiado tiempo pendientes y compáralos con tus registros de pagos. Registra cada respuesta de la API y cada webhook para soporte.
x-api-key: sk_live_…
{ "id": "order_1024", "status": "paid" }Consejos de arquitectura
Mantén el código de pagos en un servicio pequeño, separado de las vistas del checkout. Así puedes cambiar el manejador de webhook o añadir un segundo canal sin tocar el resto de la tienda.
FAQ
¿Qué lenguajes de backend puedo usar?
Cualquiera que pueda enviar un POST HTTPS con cuerpo JSON y recibir un webhook. La API es HTTP plano, así que no se requiere SDK.
¿Dónde debo poner la URL del webhook?
Usa un endpoint HTTPS público en tu backend. Debe aceptar POST y comprobar la cabecera x-api-key antes de actualizar un pedido.
¿Necesito una integración distinta para cada criptomoneda?
No. El cliente elige activo y red en la página de pago alojada, así que tu backend crea un pago en USD y lee un estado.
¿Puedo probar toda la integración primero?
Sí. Usa el flujo de factura de demostración para pagar una factura de prueba y confirma que tu manejador de webhook se ejecuta antes de aceptar pagos reales.
