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.

A checkout page on a computer: your order summary on the right, the widget in the main column, with the QR code and the other ways to pay on its left and the progress on its right. 1 2 3 4 5 The same page on a phone: the order total, then the widget with a Pay with SpiffyVault button, Pay another way folded under it, and the progress. 1 2 6 4 5
  1. Your page. The order and its total are yours to show; the widget shows only the amount.
  2. 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.
  3. The QR code, with the amount under it, for the payer to scan with the app on their phone.
  4. 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.
  5. The progress, from your server's status answers. When it is paid, the widget calls onPaid and you send the payer on to your own thank-you page.
  6. 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

The steps

stepShown as
shownThe link, with the time left
phone-connectedThe payer's app has the invoice
checkingThe payee has the payment and is checking it
on-the-wayBroadcast. With path: 'peerpay', a note says the shop collects it
in-mailboxLeft in the payee's mailbox while it was away
paidThe paid view, with a link to the transaction. onPaid is called once and the questions stop
refusedWhy (reason), that nothing was taken, and to try again. The request stays open
expiredA 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

The Payments reference has what the payee does with each payment, every error, and what you trust.