Crypto payment widget: how to add it to your website
Crypto payment widget guide: integrate the Qvard embedded checkout widget on your site. Two payment creation methods, webhook signature verification, and demo.
A crypto payment widget is a JavaScript widget that opens a payment window on your site. The Qvard widget is now live at https://qvard.com/checkout.js. This guide explains how it works and how to integrate it.
What a crypto payment widget is
A widget is a compact payment element that a site embeds to start a payment. On Qvard, the widget opens the same payment page your customers see in a modal or inline form. The customer chooses the crypto asset and network, and the amount is fixed by your order.
How it works at Qvard
The Qvard widget loads from https://qvard.com/checkout.js and opens a payment window as either a modal (popup) or inline. The window is the same hosted payment page: the customer chooses the asset and network at a fixed rate for the duration of the invoice. A widget instance receives your public key (qvard_pk_…) for browser-side creation, or a payment id for server-side creation. See the playground at https://qvard.com/en/embedded-checkout/playground/ to try it live.
<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();Two ways to create the payment
Browser-side: pass the public key (qvard_pk_…) and amount to the widget; it creates the payment and handles the window. Server-side: your backend creates the payment via POST /api/v1/payment and passes the payment id to the widget. For orders with fixed prices or inventory limits, use server-side creation so the price cannot be changed in the browser. Alternatively, skip the widget and redirect customers to the hosted payment page.
The backend call
Your server sends the order id as id and the price in USD as price, with the x-api-key header. The response returns the payment id and redirectUrl. Pass the id to the widget in the browser, or use the redirectUrl for a redirect. Never send the secret key (qvard_sk_…) to the browser.
Verify the payment from the webhook
When the status is paid, your webhook endpoint receives the id and status, signed with the X-Qvard-Signature header (HMAC-SHA256). Verify the signature using your secret key (qvard_sk_…) and check that the amount matches your order. Mark the order as paid only after signature verification. Note: the widget onSuccess event is not proof of payment.
When to choose the embedded window
Use the embedded modal or inline widget to keep customers on your page. The hosted page with a redirect works equally well and is an option when you prefer not to embed the payment window. Both share the same payment creation and webhook flow.
FAQ
Is the crypto payment widget available at Qvard today?
Yes. Load the widget from https://qvard.com/checkout.js and pass your public key (qvard_pk_…) for browser-side creation, or create the payment server-side and pass the id.
How do I add the widget to my site?
Include the <script src="https://qvard.com/checkout.js"></script> tag and instantiate QvardCheckout with your key, amount, and mode (modal or inline). See the code examples in this article and the demo.
Does the widget keep customers on my site?
Yes, with the modal or inline mode. The redirect to the hosted page takes the customer away, but returns them via a link when the payment is done.
How do I test the flow?
Create a demo payment and confirm that your webhook handler receives the signed status and matches the amount, before you go live.
