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.
| # | Layout | mode / presentation | Payer context | What renders |
|---|---|---|---|---|
| a | Inline connect | inline, intent connect | Logged in at merchant | Merchant-scoped accounts (no auth on reuse) + network accounts (auth required) + new-bank path |
| b | Inline connect | inline, intent connect | Logged out at merchant | Network accounts resolved from payerHint / DRUO cookie + new-bank path |
| c | Inline connect | inline, intent connect | First-time user, no DRUO profile | Key entry + bank search + first-time trust panel |
| d | Inline checkout | inline, intent payment | All three contexts above | Same three panels plus authorization statement and Pay CTA |
| e | Inline checkout + save | inline, allowSaveAccount: true | Any | Adds the save-for-future checkbox |
| f | Button connect | button + redirect | Any | Button → full-page DRUO flow → returns to returnUrl |
| g | Button connect | button + popup | Any | Button → druo.com popup → postMessage result |
| h | Button connect | button + modal | Any | Button → same inline surface inside an overlay |
| i | Button pay | button, intent payment, any presentation | Any | Same three, with the save option available |
| j | Buy now | button, intent buy_now | Any | Product-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.
| completion | Renders | Merchant work |
|---|---|---|
component | DRUO's own CTA ("Pay $48.20 from bank", "Connect account", …), including busy state | None — listen to success / error |
merchant | No CTA. The component only resolves the instrument and reports readiness | Render your own button, enable it on change.complete, call handle.submit() |
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.
<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.
{
"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:
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
successas 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
| Event | Payload | Fired when |
|---|---|---|
ready | { hasMerchantAccounts, hasNetworkAccounts, hasDruoProfile } | Details resolved, skeleton replaced |
authStart | { presentation, target } | Authentication surface opens |
authResult | { phase, method } | success / failed / interrupted |
success | see the section above | resultToken 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:
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.

