Skip to main content

​
Invalid Card Number

Decline code: invalid_number Error type: card_error HTTP status: 201 Created (payment status becomes failed asynchronously) WL error code: 14

​
What it means

The card number provided is not a valid credit or debit card number. The issuing bank or card network rejected the transaction because the card number fails basic validation (Luhn check) or does not correspond to any known card.

​
Why it happens

  • The customer mistyped their card number (transposed digits, missing digits).
  • The card number was copied incorrectly from the physical card.
  • The card number belongs to a card that has been cancelled and replaced with a new number.
  • The card number is from a virtual card that has been deactivated.
  • An auto-fill or password manager inserted incorrect card data.

​
API response

The payment is created with status: "pending". After processing, it transitions to failed with decline details: 
{
  "id": "pay_abc123",
  "status": "failed",
  "decline_code": "invalid_number",
  "decline_message": "The card number is not a valid credit card number."
}

​
What to tell the customer

The card number you entered is invalid. Please check the number and try again, or use a different card.
Be specific — the issue is with the card number itself, not a general decline. This helps the customer fix the problem quickly.

​
What the merchant should do

  1. Highlight the card number field in your payment form so the customer knows exactly what to fix.
  2. Implement Luhn validation client-side before submitting to the API — this catches most typos instantly without an API round-trip.
  3. Show the card brand icon based on the first digits so the customer can visually confirm they entered the right card.
  4. Do not retry automatically — the same invalid number will always fail.
  5. Do not flag as fraud — this is almost always a typo, not a malicious attempt.

​
Prevention

  • Client-side Luhn check — validate the card number format before submitting. This is the most effective way to prevent invalid_number declines.
  • Input formatting — auto-format the card number with spaces (e.g., 4111 1111 1111 1111) so the customer can visually verify groups of digits.
  • Card brand detection — show the detected brand (Visa, Mastercard) based on the BIN prefix to give the customer confidence they entered the right number.