Enter at least two characters to search. Searching documentation… No matching sections. Try an endpoint, field or event name.
Embedded checkout
View as MarkdownLoad one script from VeliraPay and open a payment link, an invoice or a charge in a window over your page, or show it inside the page. The customer never leaves your site, and your page hears when the payment is detected, paid or closed.
On this page
A payment button
Add the script and mark a link to a payment link's, an invoice's or a charge's checkout page. The payment link page in the dashboard gives you this snippet in your brand colour. Where the script cannot load, the link still opens the checkout in a new tab.
Copy failed. Select the code and copy it manually.
<script src="https://velirapay.com/js/checkout.js" async></script>
<a href="https://velirapay.com/pay/7hq2mvk4rx9t" data-velirapay="modal" target="_blank" rel="noopener">Pay with crypto</a>
Opening a charge from your page
Create the charge on your server with POST /v1/charges, which keeps your API key off the page, and hand its checkout_url to VeliraPay.open(). The window closes with its button or the Escape key.
Copy failed. Select the code and copy it manually.
// checkout_url comes from the charge your server created with POST /v1/charges.
const checkout = VeliraPay.open(order.checkoutUrl, {
on: {
'charge.payment_detected': () => showStatus('Payment detected, waiting for confirmations…'),
'charge.paid': (charge) => showStatus('Paid. Thank you!'),
'checkout.closed': ({ charge }) => refreshOrderFromServer(),
},
});
Inside your page
VeliraPay.mount() shows the checkout in an element of your page, as tall as its content, or mark the element with data-velirapay-embed.
Copy failed. Select the code and copy it manually.
const checkout = VeliraPay.mount('#payment', order.checkoutUrl);
checkout.on('*', (name, data) => console.log(name, data));
Copy failed. Select the code and copy it manually.
<script src="https://velirapay.com/js/checkout.js" async></script>
<div data-velirapay-embed="https://velirapay.com/i/9xk3cwp2hm4q"></div>
Options
| Field | Type | Description |
|---|---|---|
on
object
|
object | Functions to call for events, by name, as with checkout.on(name, function). |
navigate
boolean
|
boolean | false to handle checkout.navigate yourself instead of the page going to the address. |
confirmClose
boolean
|
boolean | open() only: false to close the window at once even while a payment is open. Unless set, a customer who closes it with its button or the Escape key while their payment is open or confirming is asked first, in the checkout's language. |
title
string
|
string | The frame's accessible name. "Checkout" unless set. |
height
string
|
string | mount() only: the frame's height until the page reports its own. "640px" unless set. |
Events
open() and mount() return a checkout you can call on(name, function), off(name, function) and close() on; on('*', function) hears every event with its name. Each event is also dispatched as a DOM event named velirapay: and the event name, on the marked link or element, that bubbles up to document.
| Field | Type | Description |
|---|---|---|
checkout.ready
object
|
object | The page in the frame has loaded. data.path is its path. |
charge.updated
charge
|
charge | Every time the checkout shows a charge, and again whenever it changes. |
charge.payment_detected
charge
|
charge | A transfer has been seen and is confirming. The page keeps waiting on its own. |
charge.paid
charge
|
charge | The charge is accepted as paid, including a short payment within your tolerance or one you accepted manually. |
charge.underpaid
charge
|
charge | Less than the amount arrived. |
charge.expired
charge
|
charge | The rate lock ended before anything arrived. |
charge.canceled
charge
|
charge | The customer canceled the charge on the checkout, or you did while it was showing. |
checkout.navigate
object
|
object | The customer chose to go back to your site (the success or cancel address); data.url is where. The script follows it unless you passed navigate: false. |
checkout.closed
object
|
object | The modal was closed, or the inline checkout removed. data.charge is the last charge it showed, or null. |
Copy failed. Select the code and copy it manually.
document.addEventListener('velirapay:charge.paid', (event) => {
console.log('Paid', event.detail.id);
});
A charge event carries the charge as the checkout shows it, without who pays:
| Field | Type | Description |
|---|---|---|
id
string
|
string | The charge's id, as in the API. |
phase
string
|
string | awaiting, confirming, paid, underpaid, expired or canceled. |
status
string
|
string | The charge's status, as in the API. |
payment_link, invoice
string|null
|
string|null | The id of the payment link or invoice it was started from. |
fiat_amount, fiat_currency
string
|
string | The price. |
asset, asset_amount, received_amount, remaining_amount
string|null
|
string|null | The coin and what is due, received and still missing in it. |
expires_at, paid_at
string|null
|
string|null | When the rate lock ends, and when it was paid. |
receipt_url
string|null
|
string|null | The receipt, once paid. |
Fulfil orders from webhooks
These events run in the customer's browser, which they control, so use them to update your page and never to ship an order. Ship when your server receives charge.paid, or reads the charge from the API. Webhooks
Where it works
Your page has to be served over https, or from localhost or 127.0.0.1 while you develop: the checkout lets itself be framed by the page that asked for it and by nothing else, and talks to that page alone. Every other part of VeliraPay refuses to be framed.
Until you name your own sites, any site may show your checkout. To keep the others from it, list yours under your organization's Domains settings, in "Sites that can show your checkout", such as https://shop.example: the checkout then refuses every other site's frame. Links to it keep working everywhere.
If your site sends a Content-Security-Policy, allow the script and the frame:
Copy failed. Select the code and copy it manually.
script-src https://velirapay.com;
frame-src https://velirapay.com;
In a frame, the checkout leaves out the buttons that would open a wallet app or the WalletConnect window, since those would take the customer away from your page; the address, the amount and the QR code are all there, and a link opens the checkout in a tab of its own. Browsers that refuse a frame cookies of its own still take the payment; they only forget the language picked, and a coin switch there leaves the first payment request open until it expires.