Enter at least two characters to search. Searching documentation… No matching sections. Try an endpoint, field or event name.

Embedded checkout

View as Markdown

Load 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.

HTML

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.

JavaScript

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.

JavaScript

Copy failed. Select the code and copy it manually.

const checkout = VeliraPay.mount('#payment', order.checkoutUrl);

checkout.on('*', (name, data) => console.log(name, data));
HTML

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 Description
on object Functions to call for events, by name, as with checkout.on(name, function).
navigate boolean false to handle checkout.navigate yourself instead of the page going to the address.
confirmClose 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 The frame's accessible name. "Checkout" unless set.
height 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 Description
checkout.ready object The page in the frame has loaded. data.path is its path.
charge.updated charge Every time the checkout shows a charge, and again whenever it changes.
charge.payment_detected charge A transfer has been seen and is confirming. The page keeps waiting on its own.
charge.paid charge The charge is accepted as paid, including a short payment within your tolerance or one you accepted manually.
charge.underpaid charge Less than the amount arrived.
charge.expired charge The rate lock ended before anything arrived.
charge.canceled charge The customer canceled the charge on the checkout, or you did while it was showing.
checkout.navigate 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 The modal was closed, or the inline checkout removed. data.charge is the last charge it showed, or null.
JavaScript

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 Description
id string The charge's id, as in the API.
phase string awaiting, confirming, paid, underpaid, expired or canceled.
status string The charge's status, as in the API.
payment_link, invoice string|null The id of the payment link or invoice it was started from.
fiat_amount, fiat_currency string The price.
asset, asset_amount, received_amount, remaining_amount string|null The coin and what is due, received and still missing in it.
expires_at, paid_at string|null When the rate lock ends, and when it was paid.
receipt_url 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:

Content-Security-Policy

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.