Integrar un checkout de stablecoins en tu tienda online
Integra un checkout de stablecoins en tu tienda: cómo usar el widget integrado, creación de pago en navegador y servidor, y verificación de webhook.
Integrar un checkout de stablecoins significa poner una ventana de pago en USDT o USDC dentro de tu tienda online. El widget de checkout integrado de Qvard acepta stablecoins hoy. Tus clientes eligen el activo cripto y la red en la página de pago, y tú verificas el pago mediante webhook.
Qué significa checkout de stablecoins integrado
Un checkout de stablecoins integrado es una ventana de pago que se abre en tu página mediante un widget JavaScript. Puede aparecer como modal (emergente) o integrada en un elemento. Tus clientes permanecen en tu página y pagan con USDT o USDC sin irse. La ventana de pago es la misma página de Qvard en un iframe: el cliente la ve en su idioma, elige el activo stablecoin y la red, y el monto se calcula a una tasa fija para tu factura.
Cómo funciona en Qvard
El widget se carga desde https://qvard.com/checkout.js y abre una ventana de pago de stablecoins en modo modal o integrado. La ventana muestra activos y redes disponibles; el cliente elige, y se muestra el monto a enviar. El widget emite eventos: onSuccess (pago realizado), onClose (ventana cerrada), onError (pago fallido). Una instancia del widget recibe tu clave pública (qvard_pk_...) para creación en el navegador, o el id del pago para creación en el servidor. Pruébalo en la página de demostración en qvard.com.
Dos formas de crear el pago
En el navegador: pasa la clave pública (qvard_pk_...) y el monto al widget; él crea el pago y abre la ventana. El cliente puede cambiar el monto en el navegador, así que usa este método para fines informativos. Tu clave pública se puede restringir a sitios permitidos en tu panel, y las solicitudes tienen un límite de frecuencia. En el servidor: tu backend crea el pago mediante POST /api/v1/payment y pasa el id del pago al widget. Para pedidos con montos fijos o críticos, usa creación en servidor y verifica siempre el monto en tu webhook. O salta el widget y redirige clientes a la página de pago alojada.
En el servidor: crea el pago primero
Tu servidor envía una solicitud POST a /api/v1/payment con el id del pedido y el precio en USD, usando el encabezado x-api-key con tu clave secreta (qvard_sk_...). La respuesta devuelve { id, redirectUrl }. Pasa el id al widget en el navegador, o usa redirectUrl para un redireccionamiento. Mantén tu clave secreta en el servidor; la solicitud no debe hacerse desde el navegador.
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
}Verifica el pago desde el webhook
Cuando el estado es paid, tu webhook recibe { id, status }, firmados con el encabezado X-Qvard-Signature en el formato t=...,v1=... (HMAC-SHA256 con tu clave secreta). Verifica la firma usando tu clave secreta (qvard_sk_...) y asegúrate de que el monto en el webhook coincida con tu pedido. Las claves heredadas sin el prefijo qvard_sk_ también reciben el encabezado x-api-key. Marca el pedido como pagado solo después de verificar la firma. Consulta la guía de firma en la documentación de Qvard.
Cuándo elegir la ventana integrada
Usa el widget modal integrado o integrado para mantener al cliente en tu página y proporcionar un checkout de stablecoins sin problemas. La página alojada con redireccionamiento funciona igual de bien y es una opción si prefieres no integrar la ventana de pago. Ambos comparten el mismo proceso de creación de pago, flujo de webhook y verificación de firma.
FAQ
¿Está disponible el checkout de stablecoins integrado en Qvard hoy?
Sí. Carga el widget desde https://qvard.com/checkout.js y pasa tu clave pública (qvard_pk_...) para creación en el navegador, o crea el pago en el servidor y pasa el id.
¿Cómo eligen los clientes un stablecoin y red en el widget?
Los clientes ven los activos stablecoin y redes disponibles en la página de pago y eligen cuál usar. El monto a enviar se actualiza según su selección.
¿Por qué debo verificar el monto en el webhook?
El monto en el webhook es la fuente de verdad de Qvard. Siempre verifica que coincida con tu pedido, incluso si creaste el pago en el servidor, porque el cliente seleccionó el stablecoin y la red.
¿Cómo pruebo antes de ir en vivo?
Usa la página de demostración en qvard.com para probar el widget y ver eventos de webhook. Confirma que tu webhook verifica la firma y marca el pedido como pagado.
