Developers · JavaScript
Checkout widget
mountPayment() puts the whole payment step into one element on your checkout page: the QR code, the button that opens the app on a phone, the other ways to pay, the progress, a new link when one expires, and the paid view.
Your server makes the payment request and is paid; the widget only shows the request's links and asks your server how the payment is going. It has no libp2p and no wallet in it. It is part of @spiffyvault/payments (0.2.0 and later): npm install @spiffyvault/payments.
Where it goes
The widget is one element on your own checkout page. Everything around it stays yours: your header, the order and its total, and the page the payer goes to once it is paid.
- Your page. The order and its total are yours to show; the widget shows only the amount.
- The element you mount into, for example
<div id="pay">. On a computer the widget lays the QR code beside the rest, so give it the main column, some 520 px wide. Below 560 px it stacks into one column. - The QR code, with the amount under it, for the payer to scan with the app on their phone.
- Other ways to pay, under the QR code: open the app on this computer, PeerPay from any BRC-100 wallet (when the request has a PeerPay link), or copy the link. On a phone they fold under Pay another way, with the QR code for another device.
- The progress, from your server's status answers. When it is paid, the widget calls
onPaidand you send the payer on to your own thank-you page. - On a phone, a Pay with SpiffyVault button opens the app on the same phone.
Try it
This is the real widget, with this page standing in for the shop's server. Switch between a computer and a phone, and move a payment along. Its link is signed by a demo payee that is never online and has no mailbox, so if you scan it, the app stops before anything is spent.
Pay for order 1042
On your server
The payee is a node on your server that takes payments with acceptLivePayments (Be paid live). For each order it makes a request:
import { createPaymentRequest } from '@spiffyvault/payments';
// The payee's links for this order: live, signed with its peer key, and PeerPay.
const request = await createPaymentRequest(
{ network: 'testnet', peerId: payee.peerId, paymentKey: payee.paymentKey,
signer: payee.privateKey, domain: 'shop.example' },
{ id: order.id, amountSats: order.totalSats, memo: `Order ${order.id}` });
Keep request.ref with the order. The payer's note carries it (ref K7Q2M9XD), so refInNote() matches a payment that arrives late, or by PeerPay, to its order. Pass the request to your page as JSON.
Your payee must check each request and payment against the order: the payer's app sets the amount, and the package knows nothing of your orders. See Match payments to your orders.
While the request is open, your server answers the widget's status question with a RequestStatus. Your payee's onPayment marks the order paid. Answer only the browser that placed the order: a status carries the txid.
return order.paidTxid !== undefined
? { id: order.id, step: 'paid', path: 'live', txid: order.paidTxid }
: { id: order.id, step: 'shown' };
On the page
import { mountPayment } from '@spiffyvault/payments/widget';
const json = async res => {
if (!res.ok) throw new Error(`shop answered ${res.status}`);
return await res.json();
};
const stop = mountPayment(document.getElementById('pay'), {
// A new request, or a fresh one when the payer asks again after it expired.
request: async () => json(await fetch(`/orders/${orderId}/payment`, { method: 'POST' })),
status: async id => json(await fetch(`/orders/${id}/payment`)),
onPaid: () => location.assign(`/orders/${orderId}/thanks`),
accent: '#0b6e4f',
});
mountPayment returns a function that stops the widget and removes it.
What the payer sees
- On a computer: the QR code with the amount, and under it the other ways to pay: open the app on this computer, PeerPay from any BRC-100 wallet, or copy the link. The progress is beside it.
- On a phone: a Pay with SpiffyVault button that opens the app, with Pay another way folded under it (the QR code for another device, PeerPay, copy the link), then the progress.
The steps
step | Shown as |
|---|---|
shown | The link, with the time left |
phone-connected | The payer's app has the invoice |
checking | The payee has the payment and is checking it |
on-the-way | Broadcast. With path: 'peerpay', a note says the shop collects it |
in-mailbox | Left in the payee's mailbox while it was away |
paid | The paid view, with a link to the transaction. onPaid is called once and the questions stop |
refused | Why (reason), that nothing was taken, and to try again. The request stays open |
expired | A Make a new link button, which calls request(previous) |
While your payee cannot take live payments, set payeeOnline: false on the request or a status. The widget then says the payment will wait for the shop, and the app pays by mailbox or PeerPay. Your server collects those with acceptOfflinePayments and acceptPeerPayPayments (Be paid while you are away).
Options
pollEvery: milliseconds between status questions, 2000 by default. Passsubscribe(id, onStatus)to push changes instead (Server-Sent Events or a WebSocket); the questions then slow to one every 15 seconds. The widget also asks at once when the page comes back into view.accent: your colour for the main button and the current step. The widget takes its font and text colour from your page.styles: false: the widget adds one stylesheet (<style id="spiffyvault-pay-styles">). Withfalse, style thespiffyvault-pay-*classes yourself. If your Content Security Policy refuses inline styles, serve@spiffyvault/payments/widget.css(the same stylesheet, as a file) from your own site and passstyles: false.labels: any of the words the widget shows, for your language.englishPaymentLabelshas them all.onEvent: each request, status, choice and error, for logging or a developer view.device:'phone'or'computer', when you know better than the browser's user agent.
The Payments reference has what the payee does with each payment, every error, and what you trust.