DRUO
Get started
Components

Layouts, slots & events

Layout permutations, loading states, slots, returned tokens, events and tamper protection.

Layouts and permutations

Every layout runs the same state machine and validation; only the surface differs.

#Layoutmode / presentationPayer contextWhat renders
aInline connectinline, intent connectLogged in at merchantMerchant-scoped accounts (no auth on reuse) + network accounts (auth required) + new-bank path
bInline connectinline, intent connectLogged out at merchantNetwork accounts resolved from payerHint / DRUO cookie + new-bank path
cInline connectinline, intent connectFirst-time user, no DRUO profileKey entry + bank search + first-time trust panel
dInline checkoutinline, intent paymentAll three contexts aboveSame three panels plus authorization statement and Pay CTA
eInline checkout + saveinline, allowSaveAccount: trueAnyAdds the save-for-future checkbox
fButton connectbutton + redirectAnyButton → full-page DRUO flow → returns to returnUrl
gButton connectbutton + popupAnyButton → druo.com popup → postMessage result
hButton connectbutton + modalAnyButton → same inline surface inside an overlay
iButton paybutton, intent payment, any presentationAnySame three, with the save option available
jBuy nowbutton, intent buy_nowAnyProduct-page button; amount comes from the component config or amount

Account scopes shown in the list:

  • Merchant account — already connected to *this* merchant. Reuse does not require a new DRUO authentication.
  • Network account — connected to DRUO through another merchant. Reuse does require authentication before it can be used here.

Who owns the complete button (inline only)

The inline component ships in two completion modes.

completionRendersMerchant work
componentDRUO's own CTA ("Pay $48.20 from bank", "Connect account", …), including busy stateNone — listen to success / error
merchantNo CTA. The component only resolves the instrument and reports readinessRender your own button, enable it on change.complete, call handle.submit()
javascript
const c = Druo.mount("#druo", {
  componentId: "cmp_9f2",
  intent: "payment",
  amount: 4820,
  completion: "merchant",
});

c.on("change", (s) => {
  // s = { complete, busy, label: "Chase Checking ••••4821", source: "connected_account" | "payment_key" | "new_account" }
  payBtn.disabled = !s.complete;
  payBtn.textContent = s.busy ? "Working…" : "Place order";
});
payBtn.onclick = () => c.submit();

Authorization consent stays inside the component in both modes — the merchant's button never substitutes for the payer's explicit authorization.

Skeleton and loading

Druo.mount paints a skeleton immediately, shaped like the layout the session will resolve to (mode, and expectedAccounts when you know the payer has saved accounts). The skeleton is replaced in place once Get Component Details returns, so the checkout never reflows and never shows a blank gap.

Embeddable slots

Pieces of the component can live anywhere on the page. Any slot rendered outside the widget is removed from the widget body, so nothing is duplicated.

html
<span data-druo-slot="logo"></span>         <!-- official DRUO wordmark -->
<span data-druo-slot="badge"></span>        <!-- framed payment-method badge -->
<span data-druo-slot="reward-badge"></span> <!-- offer: pill | line | banner -->
<span data-druo-slot="speed"></span>
<div  data-druo-slot="trust"></div>
<div  data-druo-slot="security"></div>

The reward/offer element and the trust slots are independent components: the offer renders only when Get Component Details returns a rate (variant: pill, line or banner), and the trust slots (trust, security, speed, terms) can be positioned separately from the widget body.

Add data-druo-component-id="cmp_9f2" to a slot to bind it to one instance when several components are on the same page.

What the component returns

The browser never receives account numbers and never moves money. Every terminal result is a short-lived, single-use token your server exchanges.

json
{
  "intent": "payment",
  "type": "transaction",
  "resultToken": "rtok_1P9x...",
  "intentUuid": "int_8f21",
  "accountUuid": "acc_5512",
  "financialAccountUuid": "fac_77a1",
  "orderId": "NW-10422",
  "amount": 4820,
  "currency": "USD",
  "authenticationUuid": "ida_9931",
  "institution": "Chase",
  "mask": "••••4821",
  "savedForMerchant": true,
  "reward": { "rate": 0.01, "amount": 48 },
  "expiresAt": "2026-08-27T04:20:00Z"
}

connect returns the same shape with type: "connection", no amount, and an accountUuid you can store as the durable payment method.

Your server then confirms:

http
POST https://api.druo.com/v1/intents/confirm
Authorization: Bearer sk_live_...
Idempotency-Key: NW-10422-confirm-1
Content-Type: application/json

{ "resultToken": "rtok_1P9x...", "amount": 4820, "currency": "USD" }

For connect, exchange at POST /v1/accounts/attach to bind accountUuid to your customer record.

Rules:

  • Treat success as a UI signal. Ship only after your server confirms.
  • Tokens expire in 10 minutes and burn on first use.
  • Always send an Idempotency-Key.
  • Never trust amounts posted back from the browser — confirm against your own order record.

Events

EventPayloadFired when
ready{ hasMerchantAccounts, hasNetworkAccounts, hasDruoProfile }Details resolved, skeleton replaced
authStart{ presentation, target }Authentication surface opens
authResult{ phase, method }success / failed / interrupted
successsee the section aboveresultToken issued
error{ code, message }Terminal failure
cancel{ stage }Payer dismissed the modal/popup

Handle methods: on, off, update, submit, reset, destroy, getState.

Payload tamper protection (optional)

When enabled on the component, DRUO rejects any session whose payload hash does not match. Compute server-side and render into the page:

text
payloadHash = HMAC_SHA256(secret, componentId + "|" + amount + "|" + currency + "|" + orderId)

With protection ON and a missing or mismatched hash, Get Component Details returns payload_hash_mismatch and the component renders an inline error instead of the payment surface.