Inside the component
Input paths, validation, CTA gating, authentication, trust layer, edge cases and responsive behavior.
Input paths inside the component
Exactly one of three paths produces a payable instrument.
Connected accounts
Merchant-scoped accounts render first (tag Saved here), then network accounts (tag DRUO network). Each row: bank avatar, bank name, account type, masked number, last-used copy. Single-select, first row preselected. Use another account or key opens the new-instrument panel; Back to my connected accounts returns.
Payment key
Label Payment key, placeholder email, phone or @handle. Accepts an email, an E.164 phone number, or an @handle. Resolution is debounced 350 ms against the DRUO directory. On success the field turns success-colored and shows Key found · <institution> <mask>. An inline What's a key? panel expands in place — there are no outbound links anywhere in the component.
Mutual exclusion: while the key field is non-empty, bank search collapses out of the DOM. Once a bank is selected, the key field is disabled.
Bank search and dynamic fields
Search placeholder Search 11,000+ banks, debounced 220 ms, six results max, each with a country tag. Empty result copy: No bank matches "<query>". Try its full legal name. Selecting a bank reveals only that institution's required fields; Change clears the bank, the query and all entered values.
| Region | Fields | Constraints |
|---|---|---|
| US | Routing number, Account number | Routing: exactly 9 digits and ABA checksum; account: 4–17 digits, numeric keypad |
| CO | Document ID (CC/NIT), Account number | Doc ID: 5–12 digits; account: 4–17 digits |
| EU | IBAN | 15–34 chars, mod-97 valid, helper 22–34 characters, starting with your country code. |
Single-field institutions render full width; two-field institutions use a two-column grid at ≥640 px.
Validation rules
| Field | Rule | Fires | Invalid behavior |
|---|---|---|---|
| Payment key | Must resolve in the DRUO directory | Live (debounced); error shown only after blur | Destructive border + We couldn't find that key. Check it, or choose your bank below instead. |
| Routing | 9 digits + ABA checksum | Live, on change | CTA stays disabled |
| Account / Document ID | Numeric, length-capped, ≥4 / ≥5 digits | Live, on change | CTA stays disabled |
| IBAN | Length + mod-97 | Live, on change | CTA stays disabled |
| Terms | Must be checked | On change | CTA disabled |
Length caps are enforced at input level, so over-long pastes truncate instead of failing.
CTA gating
Enabled when: terms accepted and exactly one instrument is ready (saved account selected, key resolved, or all bank fields valid) and the component is not busy. Disabled renders at 40 % opacity with not-allowed.
Authentication surface
Required for: network accounts, payment keys and brand-new bank links. Not required when reusing a merchant-scoped saved account — that path goes straight to tokenization, which is the two-click returning-payer flow.
| Presentation | Behavior |
|---|---|
modal | druo.com iframe inside an in-page dialog; result via postMessage |
popup | 460×660 druo.com window; result via postMessage, close detection reports auth_interrupted |
redirect | Full-page navigation to DRUO and back to returnUrl with the result on the session |
Phases: pending, success, failed, interrupted. Failure and interruption keep every entered value; retry restarts at pending.
Methods are per account, not per bank. DRUO returns an ordered list of allowed methods for the specific account, device and risk level, and the component renders the right surface:
| Method | Surface |
|---|---|
PASSKEY / BIOMETRIC | WebAuthn prompt inside the page, OTP offered as fallback |
OTP (email / SMS / WhatsApp) | 6-digit code field inside the component |
MAGIC_LINK, HANDOFF_CODE | Same code field |
PASSWORD, OIDC, FINANCIAL_INSTITUTION_AUTH, GOVERNMENT_ID_VERIFICATION | DRUO-hosted modal / popup / redirect |
| session or cookie resumption | Nothing shown — already authenticated |
MICRODEPOSIT | Account saved as pending; you are notified by webhook when it verifies |
Device signals
Every request carries a device payload (fingerprint, device id, cookie availability, timezone, languages, screen, WebAuthn support). It is used to recognize returning devices, skip redundant authentications, choose methods and score risk. No form values, page content or third-party cookies are collected.
Trust layer
- Authorization statement next to the terms checkbox, naming the amount and the merchant.
Secure payment from your banksignal below the CTA.- Encryption and control copy: DRUO never stores bank credentials; every payment needs explicit approval.
- First-time panel when the payer has no accounts and no DRUO profile.
- Inline education only — no links that break the funnel.
Edge cases
| Case | Behavior |
|---|---|
| Logged in at merchant, merchant accounts exist | Accounts listed with Saved here, first preselected, no auth on reuse |
| Logged in, only network accounts | Listed with DRUO network, auth required before use |
Logged out, DRUO cookie or payerHint matches | Network accounts listed |
| No accounts, no DRUO profile | New-instrument panel + first-time trust copy |
| Invalid key | Post-blur error, guidance to use bank search |
| Auth failed / interrupted | Inline error, inputs preserved, retry available |
| Popup blocked | popup_blocked error with guidance to allow pop-ups |
| Token expired before confirm | Server confirm returns token_expired; re-mount the component |
| Payment error | Inline destructive message; nothing charged; inputs editable |
| Success | Widget replaced by a receipt panel |
Responsive behavior
Full width inside its container; bank fields two-column at ≥640 px; logo hides on small screens; all touch targets ≥44 px; numeric fields open the numeric keypad.

