Checkout Widget

Take one-off payments and subscriptions — card or Direct Debit — directly on your website. The payment form opens in a secure overlay served from our domain, so card details never touch your page (SAQ-A).

1 · Install

Load the script from our domain — don't bundle or self-host it, so you always get the latest secure build:

<script src="https://merchant.quadriel.com/widget/v1/checkout.js"></script>

2 · Take a one-off payment

Construct the widget once per page load (so the result callbacks are registered even after a 3-D Secure redirect), then call open() when the payer clicks pay:

<button id="pay">Pay £25.00</button>

<script>
  // Construct the widget on every page load and register the callbacks here.
  // A card 3-D Secure challenge sends the payer to their bank and back, which
  // destroys the open() promise — the result then arrives on these callbacks.
  const widget = new Checkout.Widget({
    publishableKey: "pk_live_your_key",
    onSuccess: function (result) {
      // result.paymentId, result.customerId, result.reference, result.amount…
      window.location.href = "/thank-you";
    },
    onError:  function (err) { alert("Payment failed: " + err.message); },
    onCancel: function ()    { /* payer closed the widget */ }
  });

  document.getElementById("pay").onclick = function () {
    widget.open({
      method: "card",
      payment: {
        type: "one_time",
        amount: 2500,                 // £25.00 in pence
        currency: "GBP",
        reference: "ORDER-991"        // your order id
      },
      customer: {
        externalId: "user-42",        // your customer id — reused on repeat payments
        name: "Jane Smith",
        email: "jane@example.com",
        address: { line1: "1 High Street", city: "London", state: "Greater London", postal_code: "EC1A 1BB", country: "GB" }
      }
    });
  };
</script>

3 · Set up a subscription

Pass a recurring payment with a schedule. Works with card or Direct Debit:

widget.open({
  method: "direct_debit",            // subscriptions work with card or Direct Debit
  payment: {
    type: "recurring",
    amount: 999,                     // £9.99 per collection
    currency: "GBP",
    reference: "SUB-2026-001",
    schedule: {
      type: "UNENDING",              // or "LIMITED"
      frequency: "MONTHLY",          // WEEKLY | FORTNIGHTLY | MONTHLY | QUARTERLY | YEARLY
      frequencyDay: 1,               // collect on the 1st
      startDate: "2026-07-01"        // first collection (optional)
    }
  },
  customer: { externalId: "user-42", name: "Jane Smith", email: "jane@example.com" }
});

4 · Handle the result

A card 3-D Secure challenge navigates the payer away and back, which destroys the open() promise — so always rely on the onSuccess / onError callbacks registered at construction, and confirm the payment server-side via a webhook before fulfilling. Re-check reference and amount on your server.

Reference

new Checkout.Widget(options)

widget.open(params)

payment

payment.schedule (recurring only)

customer

Webhooks

Confirm payments on your server. We POST signed events to your endpoint (configure it in Developers → Webhooks). Verify the x-webhook-signature HMAC over the raw body, and dedupe on event_reference:

const crypto = require("crypto");

app.post("/api/payments-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(req.body)                        // the RAW bytes, not a re-stringified object
    .digest("hex");
  const got = req.get("x-webhook-signature") || "";
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString());
  // Idempotent: skip if you've already processed event.event_reference
  if (req.get("x-webhook-event") === "checkout.completed") {
    fulfilOrder(event.reference, event.amount);
  }
  res.sendStatus(200);                       // 2xx acknowledges; we retry otherwise
});

Next steps

Building a server-side integration instead? See the REST API reference — customers, invoices, payments, mandates and webhook management, authenticated with a secret key.