Embedded crypto checkout: a payment modal on your site
Embedded crypto checkout: integrate a live payment modal or inline form via JavaScript. Server-side and browser-side payment creation, webhook verification, and demo.
Embedded crypto checkout means a payment window opens directly on your page via a JavaScript widget. It can be a modal overlay or an inline form. Qvard provides a production widget at https://qvard.com/checkout.js. This guide explains how it works and how to integrate it.
What embedded checkout means
An embedded checkout is a payment window, usually a modal, that opens over the page the customer is already on. The customer keeps the shop context and pays without leaving the site. The payment logic stays the same as on a hosted page.
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 (embedded in an element). The window is the same hosted payment page your customers see: they choose the crypto asset and network, and the amount is fixed by your order. 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.
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.
<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
}Server-side: create the payment first
Your server sends the order id and the price in USD with the x-api-key header. The response returns the payment id and the redirectUrl. Pass the id to the widget in the browser, or use the redirectUrl for a hosted redirect. Keep the key on the server, because the request must not be made from the browser.
Verify the payment from the webhook
When the status is paid, your webhook endpoint receives the id and the status, signed with the X-Qvard-Signature header (HMAC-SHA256). Check the signature using your secret key (qvard_sk_…) and verify the amount matches your order. Mark the order as paid only after signature verification.
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 embedded crypto checkout 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 payment signature matter?
Yes. Always verify the X-Qvard-Signature header in your webhook using your secret key, and check that the amount in the webhook matches your order.
Can I use the redirect instead of the embedded window?
Yes. The hosted payment page at the redirectUrl works equally well and requires no widget. Both approaches use the same API and webhook.
