Card Declined Reason Codes

A list of possible reason codes that may appear in the card.declined "reason" field
Card Declined Reason Codes
 last updated: 
November 9, 2022

When listening for the card.declined webhook, you will see a "reason" field which may explain why the card transaction was declined. Here's a list of possible reason codes with a brief explanation of each.

Reason code Description
accountInactive Account is not active or deactivated
cardInactive Card is not active or deactivated
customerCanceled Card has been canceled by the customer
doNotHonor Card is not honored at this merchant
expiredCard Card has expired
invalidAmount Invalid tranaction amount
invalidCVV Invalid card CVV code
invalidCardNumber Invalid card number
invalidIssuer Invalid card issuer
invalidMerchant Merchant is non-functional or there is a problem with the merchant configuration
invalidPIN Invalid card PIN entered
invalidTransaction Invalid format of card details. Check card info and try again. Ensure no spaces or special characters in the card number.
limitsCrossed Card limits exceeded for one of the following:
- program daily limit for all cards
- program monthly limit for all cards
- interval limit if set on the individual card
lostOrStolenCard Card marked as lost or stolen
lowBalance Insufficient balance for transaction amount
pinTriesExceeded Too many incorrect PIN attempts
restrictedCard Merchant catgeory or country is restricted
suspectedFraud Card is flagged for suspected fraud
technicalError Network error or other technical issue - try running card again
userError User error - try running card again

Here's a sample response for the card.declined webhook that illustrates the reason code:

  1. {
  2.    "eventType": "card.declined",
  3.    "data": {
  4.      "cardId": "crd-d9ee9776-f244-46d7-8d08-0f6317f61442",
  5.      "amount": "1000.00",
  6.      "currency": "USD",
  7.      "status": "closed",
  8.      "reason": "lowBalance",
  9.      "approved": "false",
  10.      "method": "",
  11.      "merchant": {
  12.        "merchantName": "CVS PHARMACY",
  13.        "merchantCity": "SAN JOSE",
  14.        "merchantState": "CA",
  15.        "merchantCountry": "CAN",
  16.        "postalCode": "",
  17.        "merchantCategory": "Bakeries",
  18.        "merchantCategoryCode": "5462"
  19.      },
  20.      "createdAt": "2021-11-15T08:13:19.650542275Z"
  21.    }
  22.  }