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
NEXT STEPReproduce check-digit failures with the step-by-step Luhn calculator
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.