VALIDATION DESIGN

Card Number Validation Errors: Order, Messages, and Test Matrix

Reducing every failure to “invalid card number” looks simple, but it makes correction harder for users and regression diagnosis harder for QA. Precise internal reasons and safe, actionable external copy work better.

Normalize first, then validate in a fixed order

Treat input as a string and remove only display characters the product explicitly accepts, such as spaces and hyphens. Then check missing input, unsupported characters, global length, candidate-network length, and finally Luhn. A fixed order gives one deterministic primary error.

Do not silently delete arbitrary characters during normalization, because a typo can become a different valid string. Leading zeroes and long digit sequences also require strings to avoid precision and formatting loss.

  • type: input is not a string; the API returns NUMBER_TYPE before batch mapping
  • empty: the string contains no usable digits
  • characters: a character other than spaces or hyphens is present
  • global_length: the digit length is outside 12–19
  • network_length: the length does not match the candidate-network rules
  • luhn: a globally plausible length fails the checksum; an empty reasons array means the local format checks passed

Separate internal reason codes from interface copy

Return stable machine-readable reason codes from the API and let the interface create language- and context-appropriate text. Automation can assert the code while content teams improve the message without breaking integrations.

Tell the user what to do next, such as checking the number of digits or entering digits only. Never turn a local pass into “card verified,” because length and Luhn cannot prove account existence or authorization.

The client improves UX; the server enforces trust

Instant client feedback reduces invalid submissions, but JavaScript validation can be bypassed. The server must re-check type, length, allowed characters, and business constraints while enforcing body and batch limits.

Share a rule version or contract suite between client and server. If code cannot be shared, keep a common reason-code definition and fixed fixture set so the UI cannot accept what the API rejects.

  • String values instead of JSON numbers
  • Request body and array limits
  • A policy for unknown fields
  • No-store responses
  • Logs limited to reason code, request ID, and necessary context

Build regression cases around one broken variable

Make each negative fixture violate one condition where possible: valid length with a bad check digit, valid Luhn with an unsupported network length, one illegal character, blank input, and an oversized batch. Single-variable cases stay easy to explain.

Assert the value before and after formatting, the masked display, accessible error association, API reason code, and log fields. Add dedicated regression cases for overlapping prefixes and length boundaries whenever the range table changes.