Embed a stablecoin checkout in your online store
Embed a stablecoin checkout (USDT, USDC) in your online store: how to use the embedded widget, browser-side and server-side payment creation, and webhook verification.
Embedding a stablecoin checkout means putting a USDT or USDC payment window inside your online store. Qvard's embedded checkout widget accepts stablecoins today. Your customers choose the crypto asset and network on the payment page, and you verify the payment via webhook.
What embedded stablecoin checkout means
An embedded stablecoin checkout is a payment window that opens on your page via a JavaScript widget. It can appear as a modal (popup) or inline (embedded in an element). Your customers stay on your page and pay with USDT or USDC without leaving. The payment window is the same Qvard checkout page in an iframe: your customer sees it in their language, chooses their preferred stablecoin asset and network, and the amount to send is calculated at a fixed rate for your invoice.
How it works at Qvard
The Qvard widget loads from https://qvard.com/checkout.js and opens a stablecoin payment window as modal or inline. The window displays available assets and networks; the customer chooses, and the amount to send is shown. The widget emits events: onSuccess (payment paid), onClose (window closed), and onError (payment failed). 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 opens the window. The customer can change the amount in the browser, so use this for informational purposes. Your public key can be restricted to allowed sites via your dashboard, and requests are rate-limited. Server-side: your backend creates the payment via POST /api/v1/payment and passes the payment id to the widget. For orders with fixed or price-critical amounts, use server-side creation and always verify the amount in your webhook. Alternatively, skip the widget and redirect customers to the hosted payment page.
Server-side: create the payment first
Your server sends a POST request to /api/v1/payment with the order id and price in USD, using the x-api-key header with your secret key (qvard_sk_...). The response returns { id, redirectUrl }. Pass the id to the widget in the browser, or use redirectUrl for a hosted redirect. Keep your secret key on the server only; the request must not be made from the browser.
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
}Verify the payment from the webhook
When the status is paid, your webhook endpoint receives { id, status }, signed with the X-Qvard-Signature header in the format t=...,v1=... (HMAC-SHA256 with your secret key). Check the signature using your secret key (qvard_sk_...) and verify the amount in the webhook matches your order. Legacy keys without the qvard_sk_ prefix also receive an x-api-key header. Mark the order as paid only after signature verification. See the signature guide at https://qvard.com/en/docs/webhook-signature/.
When to choose the embedded window
Use the embedded modal or inline widget to keep customers on your page and provide a seamless stablecoin checkout. 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, webhook flow, and signature verification.
FAQ
Is embedded stablecoin 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 customers pick a stablecoin and network on the widget?
Customers see the available stablecoin assets and networks on the payment page and choose which to use. The amount to send updates based on their selection.
Why should I verify the amount in the webhook?
The amount is the source of truth from Qvard. Always verify it matches your order, even if you created the payment server-side, because the customer selected the stablecoin and network.
How do I test before going live?
Use the demo page at https://qvard.com/en/embedded-checkout/playground/ to test the widget and see webhook events. Confirm that your webhook verifies the signature and marks the order paid.
