Checkout cripto integrado: una ventana de pago en tu sitio
Checkout cripto integrado: integra una ventana modal o formulario en línea en vivo vía JavaScript. Creación de pagos en servidor y navegador, verificación de webhook, demo.
El checkout cripto integrado significa que la ventana de pago se abre directamente en tu página mediante un widget JavaScript. Puede ser un modal (ventana flotante) o un formulario integrado. Qvard proporciona un widget listo para producción en https://qvard.com/checkout.js. Esta guía explica cómo funciona y cómo integrarlo.
Qué significa el checkout integrado
Un checkout integrado es una ventana de pago, normalmente un modal, que se abre sobre la página en la que ya está el cliente. El cliente conserva el contexto de la tienda y paga sin salir del sitio. La lógica del pago es la misma que en una página alojada.
Cómo funciona en Qvard
El widget se carga desde https://qvard.com/checkout.js y abre una ventana de pago en modo modal (ventana emergente) o integrado. La ventana es la misma página de pago de Qvard: el cliente elige el activo y la red, y la cantidad está establecida por tu pedido. Una instancia del widget recibe tu clave pública (qvard_pk_…) para creación en el navegador, o un id de pago para creación en servidor. Pruébalo en la página de demostración en https://qvard.com/en/embedded-checkout/playground/.
Dos formas de crear el pago
En el navegador: pasa la clave pública (qvard_pk_…) y la cantidad al widget; él crea el pago y abre la ventana. En servidor: tu backend crea el pago vía POST /api/v1/payment y pasa el id al widget. Para pedidos con precio fijo o límites de inventario, usa creación en servidor para que el cliente no pueda cambiar el precio en el navegador. Alternativamente, omite el widget y redirige a los clientes a la página de pago alojada.
<script src="https://qvard.com/checkout.js"></script>
new QvardCheckout({
mode: 'modal',
publishableKey: 'qvard_pk_…',
price: 10,
onSuccess: function (e) {
console.log('paid', e.paymentId);
}
}).open();x-api-key: qvard_sk_…
{
"id": "order_1024",
"price": 149.99,
"paymentSystemId": 12
}
// 201 Created
{
"data": {
"id": "8f3k2a1c",
"redirectUrl": "https://my.qvard.com/pay/8f3k2a1c"
},
"code": 201,
"message": "success",
"status": true
}En servidor: crea el pago primero
Tu servidor envía el id del pedido y el precio en USD con la cabecera x-api-key. La respuesta devuelve el id del pago y el redirectUrl. Pasa el id al widget en el navegador, o usa el redirectUrl para un redirección alojada. Guarda la clave en el servidor, porque la solicitud no debe hacerse desde el navegador.
Verifica el pago desde el webhook
Cuando el estado es paid, tu endpoint de webhook recibe el id y el status, firmados con la cabecera X-Qvard-Signature (HMAC-SHA256). Verifica la firma usando tu clave secreta (qvard_sk_…) y comprueba que la cantidad coincida con tu pedido. Marca el pedido como pagado solo después de verificar la firma.
Cuándo elegir la ventana integrada
Usa el modal integrado o el formulario en línea para mantener a los clientes en tu página. La página de pago alojada con redirección funciona igual de bien y es una opción si prefieres no integrar la ventana de pago. Ambos enfoques comparten el mismo API y webhook.
FAQ
¿Está disponible hoy el checkout cripto integrado en Qvard?
Sí. Carga el widget desde https://qvard.com/checkout.js y pasa tu clave pública (qvard_pk_…) para creación en navegador, o crea el pago en servidor y pasa el id.
¿Cómo agrego el widget a mi sitio?
Incluye la etiqueta <script src="https://qvard.com/checkout.js"></script> e instantancía QvardCheckout con tu clave, cantidad y modo (modal o integrado). Mira los ejemplos de código en este artículo y en la demo.
¿Importa la firma del pago?
Sí. Siempre verifica la cabecera X-Qvard-Signature en tu webhook usando tu clave secreta, y comprueba que la cantidad en el webhook coincida con tu pedido.
¿Puedo usar la redirección en lugar de la ventana integrada?
Sí. La página de pago alojada en el redirectUrl funciona igual de bien y no requiere widget. Ambos enfoques usan el mismo API y webhook.
