DRUO
Get started
Components

Copy-paste recipes

Ready-to-use snippets for every intent, React, server-side confirmation and more.

Every snippet below is complete. Replace only the values in ALL_CAPS or the pk_test_… / cmp_… placeholders, drop it into your page, and it runs. Each recipe is followed by a worked example: what the payer actually sees and the exact payload your handlers receive.

Live prototypes: open /recipes in this demo app to see each recipe below running as a working prototype, side by side with the same code, against a sandbox that stands in for api.druo.com.

Inline checkout — DRUO owns the button

html
<div id="druo-checkout"></div>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  const checkout = Druo.mount("#druo-checkout", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_COMPONENT",
    intent: "payment",
    mode: "inline",
    completion: "component",
    amount: 4820,                       // minor units
    currency: "USD",
    orderId: "ORDER_ID",
    merchantCustomerRef: "CUSTOMER_ID", // omit for logged-out payers
    allowSaveAccount: true,
    locale: "en",
  });

  checkout.on("ready", (s) => console.log("druo ready", s));
  checkout.on("success", async (result) => {
    const res = await fetch("/api/druo/confirm", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ resultToken: result.resultToken, orderId: result.orderId }),
    });
    if (res.ok) window.location.href = "/order-confirmed?order=" + result.orderId;
  });
  checkout.on("error", (e) => alert(e.message));
  checkout.on("cancel", () => console.log("payer dismissed"));
</script>

Example — Nordstrom checkout, cart total $48.20, shopper logged in as cus_8812.

The shopper sees the DRUO card with their two saved accounts (Chase ••4821, Bank of America ••7702), a "Get 1% back" pill, and a green Pay $48.20 button. They tap the Chase row, tap Pay, approve with a passkey, and the button turns into a checkmark. Your success handler receives:

json
{
  "type": "payment",
  "intentUuid": "int_2f8c41a0d3",
  "resultToken": "rt_live_9c1f…a72e",
  "status": "SUCCEEDED",
  "orderId": "NS-100482",
  "amount": 4820,
  "currency": "USD",
  "account": { "uuid": "fa_71bd", "institution": "Chase", "mask": "4821", "type": "CHECKING" },
  "authentication": { "method": "PASSKEY", "at": "2026-09-01T11:02:44Z" },
  "reward": { "rateBps": 100, "amount": 48, "currency": "USD" }
}

Your /api/druo/confirm endpoint exchanges resultToken for the confirmed intent and only then marks order NS-100482 as paid.

Inline checkout — your own button (`completion: "merchant"`)

html
<div id="druo-checkout"></div>
<button id="place-order" disabled>Place order</button>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  const payBtn = document.getElementById("place-order");

  const checkout = Druo.mount("#druo-checkout", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_COMPONENT",
    intent: "payment",
    completion: "merchant",
    amount: 4820,
    currency: "USD",
    orderId: "ORDER_ID",
  });

  checkout.on("change", (s) => {
    payBtn.disabled = !s.complete || s.busy;
    payBtn.textContent = s.busy ? "Processing…" : "Place order";
  });
  payBtn.addEventListener("click", () => checkout.submit());
  checkout.on("success", (r) => fetch("/api/druo/confirm", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ resultToken: r.resultToken }),
  }));
</script>

Example — same $48.20 cart, but your existing Place order button drives it.

Place order stays disabled until the shopper picks an account or completes the bank fields. Each keystroke fires change:

json
{ "complete": false, "busy": false, "method": "new_account",
  "institution": "Wells Fargo", "fields": { "routingNumber": true, "accountNumber": false } }

Once complete: true the button enables; clicking it calls checkout.submit(), which opens the authentication surface and then emits the same success payload as the section above

Account connection (`intent: "connect"`)

html
<div id="druo-connect"></div>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  const connect = Druo.mount("#druo-connect", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_CONNECT_COMPONENT",
    intent: "connect",
    mode: "inline",
    merchantCustomerRef: "CUSTOMER_ID",
  });

  connect.on("success", async (r) => {
    // r.type === "connection", r.accountUuid is the durable payment method
    await fetch("/api/druo/attach", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ resultToken: r.resultToken, customerId: "CUSTOMER_ID" }),
    });
  });
</script>

Example — a payouts settings page for user cus_8812 with no bank on file.

The component shows the first-time panel: bank search, then Wells Fargo's US field set (routing 9 digits + account number), and a Connect account button. No amount is displayed anywhere. On success:

json
{
  "type": "connection",
  "intentUuid": "int_c40aa9",
  "resultToken": "rt_live_4be2…10cd",
  "accountUuid": "fa_9a31",
  "account": { "institution": "Wells Fargo", "mask": "0148", "type": "CHECKING", "country": "US" },
  "status": "SUCCEEDED"
}

You POST resultToken to /api/druo/attach, store fa_9a31 against cus_8812, and render "Wells Fargo ••0148" in your settings UI.

Subscription

html
<div id="druo-subscription"></div>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  const sub = Druo.mount("#druo-subscription", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_SUBSCRIPTION_COMPONENT",
    intent: "subscription",
    amount: 1900,          // amount of the first charge, minor units
    currency: "USD",
    orderId: "PLAN_PRO_MONTHLY",
    merchantCustomerRef: "CUSTOMER_ID",
  });

  sub.on("success", (r) => fetch("/api/druo/confirm", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ resultToken: r.resultToken, plan: "PLAN_PRO_MONTHLY" }),
  }));
</script>

Example — "Pro monthly, $19.00/mo" upgrade page.

The CTA reads Subscribe $19.00 and the authorization line reads "By clicking Subscribe you authorize recurring debits of $19.00 to Pro monthly until you cancel." Success returns both the first charge and the durable mandate:

json
{
  "type": "subscription",
  "intentUuid": "int_77d0e2",
  "resultToken": "rt_live_ba01…9f33",
  "mandateUuid": "mnd_51ab",
  "accountUuid": "fa_71bd",
  "amount": 1900, "currency": "USD",
  "orderId": "PLAN_PRO_MONTHLY",
  "status": "SUCCEEDED"
}

Store mandateUuid; later cycles are charged server-side without the payer being present.

Buy now — button on a product page

html
<div id="druo-buy-now"></div>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  const buyNow = Druo.mount("#druo-buy-now", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_BUYNOW_COMPONENT",
    intent: "buy_now",
    mode: "button",
    presentation: "modal",         // "popup" or "redirect" also valid
    amount: 4820,
    currency: "USD",
    orderId: "SKU-441-x1",
    buttonLabel: "Buy now with your bank",
  });

  buyNow.on("success", (r) => {
    window.location.href = "/order-confirmed?intent=" + r.intentUuid;
  });
</script>

Example — product page for SKU-441, $48.20.

Instead of the full card, the page renders one button: Buy now with your bank with the DRUO badge. Tapping it opens a 440px modal containing the whole experience (accounts → authorization → checkmark). No page navigation happens until you redirect:

javascript
// success
{ type: "payment", intentUuid: "int_9be2c1", resultToken: "rt_live_…",
  orderId: "SKU-441-x1", amount: 4820, currency: "USD", status: "SUCCEEDED" }
// → /order-confirmed?intent=int_9be2c1

Swap presentation: "popup" for a separate window, or "redirect" for the hosted flow in the section above

Express buttons (one-tap saved accounts)

html
<div id="druo-express"></div>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  const express = Druo.expressButtons("#druo-express", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_BUYNOW_COMPONENT",
    intent: "buy_now",
    amount: 4820,
    currency: "USD",
    orderId: "SKU-441-x1",
    merchantCustomerRef: "CUSTOMER_ID",
    maxButtons: 2,
  });

  express.on("success", (r) => {
    window.location.href = "/order-confirmed?intent=" + r.intentUuid;
  });
</script>

Example — logged-in shopper cus_8812 with three saved accounts.

maxButtons: 2 renders exactly two one-tap buttons, most recently used first:

text
[ ●● Chase ••4821 — Buy now $48.20 ]
[ ●● BofA  ••7702 — Buy now $48.20 ]

There is no account picker and no form: tapping a button goes straight to the authentication modal. A shopper with no saved accounts renders zero buttons — check express.getState().buttons.length and fall back to the section above

json
{ "type": "payment", "intentUuid": "int_e1073b", "resultToken": "rt_live_…",
  "account": { "uuid": "fa_71bd", "mask": "4821" }, "status": "SUCCEEDED" }

Button + redirect, and handling the return

html
<div id="druo-button"></div>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  Druo.mount("#druo-button", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_COMPONENT",
    intent: "payment",
    mode: "button",
    presentation: "redirect",
    amount: 4820,
    currency: "USD",
    orderId: "ORDER_ID",
    returnUrl: "https://yourstore.com/checkout/return",
  });
</script>

On https://yourstore.com/checkout/return:

html
<script src="https://js.druo.com/v1/components.js" data-key="pk_test_YOUR_KEY"></script>
<script>
  (async () => {
    const intentUuid = new URLSearchParams(location.search).get("druo_intent");
    if (!intentUuid) return;

    const intent = await Druo.retrieveIntent({ intentUuid });

    if (intent.status === "SUCCEEDED") {
      await fetch("/api/druo/confirm", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ resultToken: intent.resultToken }),
      });
      location.replace("/order-confirmed");
    } else if (intent.nextAction) {
      await Druo.handleNextAction(intent);   // finishes the pending authentication
    } else {
      location.replace("/checkout?error=" + (intent.error?.code || "failed"));
    }
  })();
</script>

Example — a mobile checkout that hands off to the DRUO hosted page.

Tapping the button navigates to https://js.druo.com/v1/redirect?intent=int_4a90f1, the payer completes the flow there, and DRUO returns them to https://yourstore.com/checkout/return?druo_intent=int_4a90f1&druo_status=succeeded.

Druo.retrieveIntent({ intentUuid }) on that page returns:

json
{ "intentUuid": "int_4a90f1", "status": "SUCCEEDED",
  "resultToken": "rt_live_…", "orderId": "ORDER_ID", "amount": 4820,
  "nextAction": null }

If the payer bounced mid-authentication you instead get { "status": "REQUIRES_ACTION", "nextAction": { "type": "otp", "channel": "sms", "hint": "•• 41" } } and Druo.handleNextAction(intent) re-opens the code entry exactly where they left off.

Secure fields (bank credentials never enter merchant scope)

html
<div id="druo-secure"></div>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  Druo.mount("#druo-secure", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_COMPONENT",
    intent: "payment",
    amount: 4820,
    currency: "USD",
    secureFields: true,
  }).on("success", (r) => fetch("/api/druo/confirm", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ resultToken: r.resultToken }),
  }));
</script>

Add to your CSP: script-src https://js.druo.com; frame-src https://js.druo.com; connect-src https://api.druo.com.

Example — the same checkout under a stricter compliance review.

Visually nothing changes: the shopper still sees "Routing and account number" in one line. Technically, those inputs live in an iframe on https://js.druo.com, so document.querySelector("input") in your page cannot read them. Your change event carries shape only, never values:

json
{ "complete": true, "fieldsToken": "ft_2b91…c7", "values": ["routingNumber", "accountNumber"] }

success is identical to the section above Appearance is forwarded into the frame, so the framed inputs inherit your fonts, radius and colors.

Custom layout with Elements

html
<div id="druo-bank"></div>
<div id="druo-fields"></div>
<div id="druo-alias"></div>
<button id="pay" disabled>Pay</button>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  const els = Druo.elements({
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_COMPONENT",
    intent: "payment",
    amount: 4820,
    currency: "USD",
  });

  els.create("institution-selector").mount("#druo-bank");
  els.create("account-fields", { verificationCode: "auto" }).mount("#druo-fields");
  els.create("alias").mount("#druo-alias");

  const payBtn = document.getElementById("pay");
  els.on("change", (s) => (payBtn.disabled = !s.complete));
  payBtn.addEventListener("click", () => els.submit());
  els.on("success", (r) => fetch("/api/druo/confirm", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ resultToken: r.resultToken }),
  }));
</script>

Example — a three-column custom checkout that does not use DRUO's card at all.

You place the institution selector in your left column, the account fields in the middle, and the alias input under a "or use a payment key" tab, all wired to your own Pay button. change reflects whichever element is active:

json
{ "complete": true, "method": "alias", "alias": "@ale.pinzon", "institution": null }

Calling els.submit() runs the same tokenization, authentication and telemetry path as the packaged component and returns the standard success payload.

Slots placed around your own page

html
<header>Checkout <span data-druo-slot="badge" data-druo-component-id="cmp_YOUR_COMPONENT"></span></header>

<div data-druo-slot="reward-badge" data-druo-component-id="cmp_YOUR_COMPONENT"></div>
<div id="druo-checkout"></div>
<div data-druo-slot="trust" data-druo-component-id="cmp_YOUR_COMPONENT"></div>
<div data-druo-slot="security" data-druo-component-id="cmp_YOUR_COMPONENT"></div>

<script src="https://js.druo.com/v1/components.js"></script>
<script>
  Druo.mount("#druo-checkout", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_COMPONENT",
    intent: "payment",
    amount: 4820,
    currency: "USD",
  });
</script>

Example — a checkout page that spreads DRUO across three regions.

The badge renders inline in your header next to "Checkout", the reward line ("Pay by bank and get $0.48 back on this order") sits above the card, and the trust and security copy render below your order summary — all fed by the same cmp_YOUR_COMPONENT configuration, so a reward-rate change in DRUO updates every slot without a code change. Slots are read-only: they never collect input.

Appearance and extra locales

html
<script src="https://js.druo.com/v1/components.js"></script>
<script>
  Druo.locales.register("fr", {
    "cta.payment": "Payer {amount} par virement",
    "trust.security": "Paiement chiffré, identifiants jamais partagés",
  });

  Druo.mount("#druo-checkout", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_COMPONENT",
    intent: "payment",
    amount: 4820,
    currency: "EUR",
    locale: "fr",
    appearance: {
      theme: "minimal",
      variables: {
        colorPrimary: "#0f9d76",
        colorTextSecondary: "#8a8f98",
        borderRadius: "14px",
        fontFamily: "Inter, system-ui, sans-serif",
      },
      rules: {
        ".Button": { borderRadius: "999px", fontWeight: "700" },
        ".Input": { borderWidth: "2px" },
      },
    },
  });
</script>

Example — a French merchant with a rounded, dark-mode brand.

javascript
Druo.mount("#druo-checkout", {
  publishableKey: "pk_live_…",
  componentId: "cmp_fr_checkout",
  intent: "payment", amount: 4820, currency: "EUR", locale: "fr",
  appearance: {
    theme: "night",
    variables: { colorPrimary: "#7c5cff", borderRadius: "18px",
                 fontFamily: "'General Sans', system-ui, sans-serif" },
    rules: { ".Button": { borderRadius: "999px" }, ".Input": { borderWidth: "2px" } },
  },
});

The card renders on #0f1115, the CTA reads Payer 48,20 € par virement in a purple pill, IBAN placeholder becomes FR76 3000 6000 0112 3456 7890 189, and the trust line uses your registered French string. Two components on one page can use two different appearances — the rules are scoped per instance.

React / Next.js component

typescript
import { useEffect, useRef } from "react";

declare global { interface Window { DRUO?: any } }

function loadDruo(): Promise<any> {
  if (window.DRUO) return Promise.resolve(window.DRUO);
  return new Promise((resolve, reject) => {
    const s = document.createElement("script");
    s.src = "https://js.druo.com/v1/components.js";
    s.async = true;
    s.onload = () => resolve(window.DRUO);
    s.onerror = () => reject(new Error("Failed to load components.js"));
    document.head.appendChild(s);
  });
}

export function DruoCheckout({ amount, orderId }: { amount: number; orderId: string }) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    let handle: any;
    let cancelled = false;

    loadDruo().then((DRUO) => {
      if (cancelled || !ref.current) return;
      handle = Druo.mount(ref.current, {
        publishableKey: process.env.NEXT_PUBLIC_DRUO_KEY,
        componentId: "cmp_YOUR_COMPONENT",
        intent: "payment",
        amount,
        currency: "USD",
        orderId,
      });
      handle.on("success", async (r: any) => {
        await fetch("/api/druo/confirm", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ resultToken: r.resultToken, orderId }),
        });
      });
    });

    return () => { cancelled = true; handle?.destroy(); };
  }, [amount, orderId]);

  return <div ref={ref} />;
}

Example — a Next.js cart page.

typescript
<DruoCheckout amount={4820} orderId="NS-100482" />

The script loads once per document even if several components render; changing the amount prop re-mounts with the new total, and unmounting the route calls handle.destroy() so no listeners leak. In React 18 StrictMode the effect runs twice in development — the cancelled flag plus destroy() makes that safe.

Server-side confirmation (Node)

javascript
// POST /api/druo/confirm
export async function confirmDruoIntent(req, res) {
  const { resultToken, orderId } = req.body;

  const order = await db.orders.findByPk(orderId);          // your own record
  if (!order) return res.status(404).json({ error: "unknown_order" });

  const r = await fetch("https://api.druo.com/v1/intents/confirm", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.DRUO_SECRET_KEY}`,
      "Idempotency-Key": `${orderId}-confirm-1`,
      "Content-Type": "application/json",
    },
    // never trust an amount sent by the browser — use your own
    body: JSON.stringify({ resultToken, amount: order.amount, currency: order.currency }),
  });

  const data = await r.json();
  if (!r.ok) return res.status(402).json({ error: data.error?.code || "confirm_failed" });

  await db.orders.update({ status: "paid", druoIntent: data.intentUuid }, { where: { id: orderId } });
  res.json({ ok: true });
}

For connect, call https://api.druo.com/v1/accounts/attach with { resultToken, customerRef } and store the returned accountUuid.

Example — request and response for order NS-100482.

http
POST /v1/intents/confirm HTTP/1.1
Host: api.druo.com
Authorization: Bearer sk_live_…
Idempotency-Key: NS-100482-confirm-1

{ "resultToken": "rt_live_9c1f…a72e", "amount": 4820, "currency": "USD" }
json
{ "intentUuid": "int_2f8c41a0d3", "status": "SUCCEEDED",
  "settlement": { "expectedAt": "2026-09-02T16:00:00Z", "rail": "ACH" },
  "accountUuid": "fa_71bd" }

Replaying the same Idempotency-Key returns the same body without moving money again. If the browser had been tampered with and sent amount: 100, the comparison against your own order.amount rejects it before this call.

Payload tamper protection (server + page)

javascript
// server
import crypto from "node:crypto";

export function druoPayloadHash({ componentId, amount, currency, orderId }) {
  return crypto
    .createHmac("sha256", process.env.DRUO_PAYLOAD_SECRET)
    .update(`${componentId}|${amount}|${currency}|${orderId}`)
    .digest("hex");
}
html
<!-- page, values rendered by your template -->
<script>
  Druo.mount("#druo-checkout", {
    publishableKey: "pk_test_YOUR_KEY",
    componentId: "cmp_YOUR_COMPONENT",
    intent: "payment",
    amount: 4820,
    currency: "USD",
    orderId: "ORDER_ID",
    payloadHash: "{{ payloadHash }}",
  });
</script>

Example — a page whose HTML was edited in devtools.

Your template renders payloadHash: "9f2c1d4b…" for cmp_YOUR_COMPONENT|4820|USD|NS-100482. An attacker changes amount to 100 in the console and remounts; the hash no longer matches, so the mount fails before any network call:

json
{ "code": "payload_hash_mismatch", "message": "Component payload does not match the signed hash" }

Delivered through the error event, with the same traceId as the mount.

Micro-deposit verification on a later visit

html
<script src="https://js.druo.com/v1/components.js" data-key="pk_test_YOUR_KEY"></script>
<script>
  document.getElementById("verify").addEventListener("submit", async (e) => {
    e.preventDefault();
    const amounts = [Number(e.target.a1.value), Number(e.target.a2.value)]; // cents
    try {
      const result = await Druo.verifyMicrodeposits("INTENT_UUID", { amounts });
      // or: { descriptorCode: "SM11AA" }
      await fetch("/api/druo/confirm", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ resultToken: result.resultToken }),
      });
    } catch (err) {
      alert(err.message);
    }
  });
</script>

Example — a brand-new account that needed two test deposits.

Three days after checkout the payer returns to /verify?intent=int_c40aa9, sees "We sent two deposits to Wells Fargo ••0148", and types 0.11 and 0.27. Successful verification returns a fresh token:

json
{ "intentUuid": "int_c40aa9", "status": "SUCCEEDED",
  "resultToken": "rt_live_31fa…88b2", "accountUuid": "fa_9a31" }

Wrong amounts throw an error with code: "microdeposit_mismatch" and attemptsRemaining; after the third failure the account is locked and must be reconnected