Widget de pago cripto: cómo añadirlo a tu sitio web
Guía del widget de pago cripto: integra el checkout integrado de Qvard en tu sitio. Creación de pagos en servidor y navegador, verificación de firma webhook, demo.
Un widget de pago cripto es un widget JavaScript que abre una ventana de pago en tu sitio. El widget de Qvard ya está en vivo en https://qvard.com/checkout.js. Esta guía explica cómo funciona y cómo integrarlo.
Qué es un widget de pago cripto
Un widget es un elemento de pago compacto que un sitio incrusta para iniciar un pago. En Qvard, el widget abre la misma página de pago que ven tus clientes en una ventana modal o formulario integrado. El cliente elige el activo y la red; la cantidad está establecida por tu pedido.
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 a un tipo fijo durante el tiempo del recibo. 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/.
<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();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.
La llamada desde el backend
Tu servidor envía el id del pedido en id y el precio en USD en price, 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 una redirección. Nunca envíes la clave secreta (qvard_sk_…) al 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. Nota: el evento onSuccess del widget no es prueba de pago.
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 widget de pago cripto de 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 instancia QvardCheckout con tu clave, cantidad y modo (modal o integrado). Mira los ejemplos de código en este artículo y en la demo.
¿El widget mantiene al cliente en mi sitio?
Sí, en modo modal o integrado. La redirección a la página alojada lleva al cliente a otro sitio, pero regresa por un enlace una vez completado el pago.
¿Cómo pruebo el flujo?
Crea un pago de demostración y confirma que tu manejador de webhook recibe el status firmado y la cantidad coincide, antes de salir en vivo.
