Bank details

Problem Context

• The product needs to pay money to a user, collect money by bank debit, refund to a bank account, set up payroll, save a payout account, or initiate an account-to-account payment.
• Accepted identifiers vary by region and rail, such as UK sort code and account number, U.S. routing and account number, IBAN, roll number, saved account selection, or bank redirection.
• Users may copy from bank apps, cards, statements, checks, employer portals, or building society passbooks and may include spaces, hyphens, or line breaks.
• Verification can produce more than one outcome: format valid, account exists, name match, close match, no match, pending micro-deposit, failed verification, or user override.
• Bank details are sensitive enough to require secure collection, masked display, access control, audit logging, and careful recovery flows.

Selection Rules

• Choose bank details when the service needs financial account identifiers for payout, debit, refund, payroll, account linking, bank transfer, or payment initiation.
• Ask for the fields required by the payment rail and country, not a generic bank details blob.
• Use sort code and account number for UK domestic account details when that is the supported payment route.
• Use routing number and account number for U.S. ACH flows, plus account type only when the processor or rail requires it.
• Use IBAN, BIC, or bank redirection when the selected country, payment rail, or open-banking flow requires those identifiers.
• Do not ask users whether they have a bank account or building society account when an optional roll number field is enough.
• Make roll number, secondary reference, or regional account addenda optional unless the user or payment provider indicates it is required.
• Accept pasted identifiers with spaces, hyphens, and common grouping, then normalize them visibly before validation.
• Validate each part separately and preserve all entered values after a failed check.
• Treat account validation, Confirmation of Payee, instant verification, and micro-deposits as verification states that users can understand and recover from.
• Show enough masked detail on review to let users recognize the account, such as account holder name, sort code, last digits, and verification status.
• Do not collect bank account details by email, chat, free-text attachment, screenshot, or unsupported file upload.
• Route bank-detail changes through review before submit when money, payroll, benefits, refunds, or account ownership will change.

Required States

• Initial secure collection state with purpose, account holder name, routing field, account number, optional roll number or regional equivalent, and hints.
• Focused entry state with persistent labels and widths that match expected identifier lengths.
• Pasted value state where spaces, hyphens, and line breaks are normalized without losing digits.
• Missing account holder name error state.
• Invalid routing identifier state with a field-specific correction.
• Invalid account number state with preserved account number and exact length or digit guidance.
• Optional roll number provided and not provided states.
• Verification pending state for micro-deposit, processor, or bank-response checks.
• Verified account match state with masked account summary.
• Close-match or name-mismatch state requiring user review.
• No-match or failed verification state with correction, alternate verification, or support path.
• Submitted or saved state that stores the account securely and shows only masked details on later pages.

Interaction Contract

• Users can paste account details from trusted sources without losing spacing, leading zeros, or roll-number characters.
• Formatting changes are visible and do not silently change the canonical account number.
• Submitting incomplete details highlights the exact missing or invalid field while preserving every typed value.
• Optional roll-number or regional fields never block users who genuinely do not have that value.
• Account validation results are displayed as match, close match, no match, pending, failed, or overridden rather than hidden behind a generic error.
• Verification that takes time creates a pending state with clear next steps and does not pretend the account is ready.
• Saved or review states mask sensitive digits while still giving users enough information to detect the wrong account.
• Changing saved bank details revalidates the new account and invalidates stale payout, debit, or payroll review state.

Implementation Checklist

• Define supported countries, payment rails, required fields, optional fields, validation services, verification outcomes, masking rules, retention policy, and audit logging before designing the form.
• Use native inputs with visible labels, stable names, inputmode settings, autocomplete settings only where appropriate, and aria-describedby for hints and errors.
• Normalize pasted sort codes, routing numbers, account numbers, IBANs, and roll numbers without dropping leading zeros.
• Validate format locally where possible and verify account existence, account name, or ownership through the chosen payment provider or banking rail where required.
• Represent close-match, no-match, pending, failed, and override outcomes explicitly in the UI and backend state.
• Mask stored details on summaries, logs, analytics, notifications, and review pages unless a user is actively editing inside a secure session.
• Avoid sending bank details through email, support tickets, event telemetry, screenshots, or file uploads.
• Test paste, deletion, mobile numeric keyboards, screen readers, zoom, saved drafts, browser Back, validation outage, micro-deposit return, provider timeout, duplicate account, and review-before-submit flows.

Common Generated-UI Mistakes

• Using one freeform field for all account details.
• Collecting bank details by email or uploaded statement when a structured secure form is available.
• Asking users to identify whether their account is a bank or building society account.
• Making building society roll number required for everyone.
• Silently stripping leading zeros or changing account numbers during formatting.
• Treating a syntactically valid account number as verified ownership.
• Showing only a generic payment failed message after a validation error.
• Masking every digit on review so users cannot recognize the account.
• Storing raw bank details in logs, analytics, local storage, or support transcripts.
• Treating bank-login account selection and manual bank-detail entry as the same recovery flow.

Critique Questions

• Which payment rail and country determine the exact account fields required?
• Can users paste details with spaces or hyphens without losing leading zeros?
• How does the UI represent account validation, name-match, pending verification, and failed verification states?
• Are roll numbers or regional addenda optional for users who do not have them?
• What masked details are shown so users can recognize the account before money moves?
• Where are raw bank details stored, logged, transmitted, and removed?
• What happens when a user changes saved bank details after a payout or debit is already in review?