Payment card entry

Problem Context

• The user is paying by card, adding a card for later use, replacing a card-on-file method, or confirming a card payment at checkout.
• The form may need card number, cardholder name, expiry month and year, CVC or CID, billing ZIP or postal code, billing country, wallet selection, supported brand detection, and authentication outcomes.
• Users copy from physical cards, wallet apps, password managers, browser autofill, or bank apps and may paste spaces, hyphens, or cardholder names in different case.
• Card brands and payment processors can impose different number lengths, CVC lengths, supported brands, billing address needs, authentication requirements, and decline responses.
• Cardholder data and sensitive authentication data require careful scope control, redaction, logging discipline, and clear retention limits.

Selection Rules

• Choose payment card entry when the task is to charge a card, verify a card, save a card payment method, or replace a card-on-file credential.
• Use hosted fields, payment elements, or processor-controlled components for PAN and CVC whenever the product does not intentionally own full card-data processing.
• Ask for card number, expiry, and CVC or CID only when needed by the payment flow, and ask for cardholder name or billing postal code when processor, fraud, AVS, tax, or receipt requirements need them.
• Support browser autofill with cc-name, cc-number, cc-exp or month and year tokens, cc-csc, cc-type when exposed, postal-code, transaction-currency, and transaction-amount as appropriate.
• Accept pasted card numbers with spaces or hyphens, then group them for readability without changing the canonical digits.
• Detect card brand and supported brand state from the entered number, but do not use a brand icon as the only validation feedback.
• Validate Luhn or processor-equivalent card number rules, supported length, expiry not in the past, CVC or CID length, and billing postal code before charging.
• Handle unsupported brand, invalid field, requires authentication, declined, processing, tokenized, saved, and succeeded states as distinct user-facing outcomes.
• Offer wallet, Link-style, or payment-request options where available, while keeping manual card entry or another accessible fallback.
• After tokenization or authorization, show only brand, last four digits, expiry when safe, billing postal code, and payment method status on review and receipts.
• Do not store, log, echo, email, chat, screenshot, or analytics-track full card numbers or CVC values.
• Do not treat a card-number mask, expiry date field, or review page as a substitute for secure card capture.

Required States

• Initial secure checkout state with amount, accepted card brands, wallet option, card number, expiry, CVC or CID, and billing postal code if required.
• Focused entry state with persistent labels, autocomplete purpose, and helper text that survives placeholder disappearance.
• Pasted card number state where spaces and hyphens are accepted and grouped for review.
• Brand detected state showing supported brand and expected CVC or CID length.
• Unsupported brand state with a clear alternate payment path.
• Invalid card number state with checksum or length correction guidance.
• Expired or impossible expiry state using month and year guidance rather than a full date picker.
• CVC or CID error state that respects three- and four-digit brand differences.
• Billing postal code required or invalid state where processor or country rules require it.
• Tokenized state where raw PAN and CVC are no longer displayed or retained by the app.
• Wallet selected state with network-token or processor-token summary and manual fallback still available.
• Requires authentication, declined, processing, succeeded, and retry states after payment submission.
• Masked review state with brand, last four digits, expiry, amount, billing context, and explicit charge action.

Interaction Contract

• Users can type, paste, autofill, delete, select, and correct card number, expiry, CVC, and postal code fields without losing entered values.
• Card number grouping helps readability but the canonical value is the digit sequence passed to the processor-hosted field or tokenization call.
• Brand feedback updates as enough digits are entered and changes CVC or CID expectations only when the brand is known.
• Submitting incomplete or invalid details keeps the entered safe-to-display values visible and focuses the first actionable error.
• Processor and wallet states are represented explicitly instead of hidden behind one catch-all payment error.
• Tokenized and saved-card states never redisplay the full PAN or CVC, and later screens cannot recover CVC from the UI.
• A final charge action uses masked card details and amount so users can detect the wrong card before payment.

Implementation Checklist

• Select the payment processor, hosted-field or payment-element integration, supported brands, card-on-file rules, wallet support, authentication requirements, billing data, and PCI scope before designing the checkout.
• Use native labels, autocomplete tokens, inputmode values, aria-describedby hints, field-specific errors, and processor-provided accessible states for hosted iframes or embedded elements.
• Normalize paste and display grouping while preserving leading digits and never copying raw PAN or CVC into app-managed state beyond what the processor component requires.
• Implement brand detection, supported-brand decisions, expiry validation, CVC or CID length checks, postal-code requirements, and processor decline or authentication recovery as separate states.
• Redact card details from logs, analytics, replay tools, support transcripts, screenshots, error payloads, local storage, and review pages.
• Show masked review details and amount before charge, and keep receipts or saved methods limited to brand, last four digits, expiry, and billing details that are safe to display.
• Test paste, autofill, mobile keyboards, saved cards, wallets, unsupported brands, American Express CID, variable-length card numbers, expired card, declined card, required authentication, network failure, retry, browser Back, zoom, screen readers, and high contrast.

Common Generated-UI Mistakes

• Using one multiline field for card number, expiry, CVC, and billing details.
• Collecting card details through ordinary app-owned inputs when hosted fields or a payment element are required by the intended compliance model.
• Assuming every card number has sixteen digits or every security code has three digits.
• Displaying or storing CVC after authorization.
• Showing a full card number on review, receipt, admin screens, or support tools.
• Blocking paste, autofill, or password-manager card filling.
• Using a wallet button as the only payment path.
• Reporting every card-entry, authentication, decline, or network issue as Payment failed.
• Saving card details before the user has seen a masked review and explicit save or charge action.

Critique Questions

• Which processor or hosted component owns PAN and CVC collection?
• Which card brands, number lengths, CVC lengths, billing data, wallets, and authentication paths are supported?
• Can users paste or autofill card details without breaking grouping, validation, or browser security controls?
• How does the UI distinguish invalid fields, unsupported brand, expired card, requires authentication, declined, processing, tokenized, and succeeded states?
• Where could raw PAN or CVC appear in logs, analytics, screenshots, support tools, browser storage, or review pages?
• What exact masked details are shown before charge so users can recognize the card without exposing sensitive data?