Taking payments

The pay button

There are two ways to put a pay button on a page. The first is a plain link, needs no script at all, and is what most sites should use. The second is a small script that draws the button and creates the checkout session itself.

A plain link

<a href="https://pay.orrerie.com/l/plink_gg6as78pk82ndt25m36vjeey">Pay with crypto</a>

Style it as you like. It works in an email, in a PDF, as a QR code and with JavaScript switched off. Each click that starts paying creates one order. The id in the address is the id of a payment link: the price lives on the link at Orrerie, so nothing on your page can change it.

The link's page takes a few query parameters (quantity, amount on an open-amount link, reference and locale). The hosted checkout lists them.

The button script

<div data-orrerie-pay
     data-payment-link="plink_gg6as78pk82ndt25m36vjeey"
     data-publishable-key="pk_live_…"
     data-label="pay_with_crypto"
     data-quantity="1"
     data-reference="1042">
  <a href="https://pay.orrerie.com/l/plink_gg6as78pk82ndt25m36vjeey">Pay with crypto</a>
</div>

<script async src="https://pay.orrerie.com/js/button.v1.1.0.0.js"
        integrity="sha384-1ODKKQy5XMIT6G3zuOsp6/xJoDZPmcI62RgF3oBuhld7hwC9mtKvyd9Kyx6E7K1S"
        crossorigin="anonymous"></script>

The script finds every element with data-orrerie-pay and draws the button inside it. On a click it creates a checkout session with the publishable key and sends the browser to the session's url. If the session call fails, or no publishable key is given, it opens the payment link's own page instead, so the button never dies silently.

Put the plain link of the payment link inside the element, as above. When the script draws the button, it hides what the element holds, so your page shows the button only. When the script cannot run (it is blocked, JavaScript is off, or the network failed), the link stays and still opens the payment link's own page. Without it, the element would stay empty.

A publishable key starts with pk_live_ or pk_test_ and is safe to put in a page. With it, Create a checkout session accepts only payment_link, quantity, amount on an open-amount link, client_reference_id and customer_email, and the link must have allow_publishable_key set to true, which is the default. Authentication describes the three kinds of key.

Attributes

The JavaScript interface

For a single-page app, mount the button or start a checkout yourself:

OrreriePay.mount(element, { paymentLink, publishableKey, label, size, theme, target });
OrreriePay.checkout({ paymentLink, publishableKey, quantity, amount, reference, email });  // creates the session and redirects
OrreriePay.version;   // "1.x.y"

Your content-security policy

If your site sends a content-security policy, it must allow the script and the one host it calls:

script-src https://pay.orrerie.com; connect-src https://api.orrerie.com

The integrity value

The script's file name carries its version: button.v1.js only ever gets compatible fixes. Each release is also served at an address of its own that never changes, such as button.v1.1.0.0.js, and has a sha384 value, published on this page, for the integrity attribute of your script tag. With it, the browser refuses to run the file if a single byte differs from the release you pinned. Pin a release's own address, never button.v1.js: its bytes change with each fix, so a pinned value would stop your button at the next one.

The current release is 1.0.0. To pin it, load the release's own address with its value. Its bytes never change, so the browser runs exactly what you pinned:

<script async src="https://pay.orrerie.com/js/button.v1.1.0.0.js"
        integrity="sha384-1ODKKQy5XMIT6G3zuOsp6/xJoDZPmcI62RgF3oBuhld7hwC9mtKvyd9Kyx6E7K1S"
        crossorigin="anonymous"></script>

To take each compatible fix as it is released, load button.v1.js instead, without an integrity value. Its bytes change with each fix, so a value pinned to it would make the browser refuse the next release:

<script async src="https://pay.orrerie.com/js/button.v1.js"
        crossorigin="anonymous"></script>

What the button never is

• Never inside your own app to sell what is used in that app. Do not place the button inside an iPhone or Android app to sell digital content used in that app.
• Never a frame or a pop-over of the checkout. Checkout pages are served with a policy that forbids framing, so that no site can draw its own content over an address or a pay button. The payer always sees pay.orrerie.com in the address bar. Open the checkout in the same tab or in a new tab, with data-target.
• Never proof of payment. The script reports nothing back to your page about success. Your page learns of a payment from your own server, which learned it from the order.paid webhook.
• Never a tracker. The script sets no cookie, uses no storage, loads nothing else and calls only api.orrerie.com. It is under 25 KB compressed as served, loads with async so it never holds up your page. Browsers keep button.v1.js for five minutes and a release's own address for a year, since its bytes never change.

Test it

Use a payment link made with a test key and a pk_test_ publishable key. The checkout that opens carries the test banner and the buttons that simulate a payment. Test mode has the rest.