Decline Reasons

What the declinedReason field on transaction webhooks means, and what to do about each common decline.

When a transaction is declined, the reason is returned in the declinedReason field of the transaction.created and transaction.updated webhooks. This page lists the common decline reasons and what you can do about each.

Declines come from several places: Rain’s system rules, card limits, risk checks, and, for partner-managed programs, your own webhook responses. What you can do about a decline covers the reasons you can act on, and Standard decline reasons lists every value Rain itself sends.

Some declines come from the card processor instead of a Rain rule. These take priority, and their declinedReason is a lowercase description supplied by the processor (for example, restricted card) rather than one of Rain’s standard values. The field can also be empty in rare cases. Match on the standard reasons, and fall back to a generic “declined” for anything you do not recognize.

What you can do about a decline

Many declines are expected outcomes you can act on. The table below maps common reasons to their cause and your next step:

Decline reason	What it means	What you can do
card spending limit exceeded	The card’s configured spending limit was reached	Review or adjust the card’s spending controls
account credit limit exceeded	Insufficient spending power / available balance for the authorization	Add collateral or funds before retrying
card locked / card canceled / card not activated	The card is not in an active state	Manage the card’s status (activate or unlock as appropriate)
invalid pin attempt limit exceeded	Too many incorrect PIN attempts; the card is automatically locked and a card.updated webhook is sent with statusChangeReason: pin_limit_exceeded	Set the card status back to active to unlock it
webhook declined / webhook timeout	For partner-managed authorization, your endpoint returned a decline or did not respond within the allowed time	Check your authorization endpoint’s response and latency
transaction declined by risk rules	The authorization was declined by Rain’s fraud risk scoring	Contact Rain support if you believe a transaction was declined in error
merchant scope mismatch	The scoped card has an allowedMerchants list and this merchant isn’t on it	Review the card’s merchant allow-list, or create a new scoped card with the right merchants
issuer unavailable	A transient system issue prevented the authorization from being decided	The cardholder can retry the transaction
restricted country	The transaction originated in a restricted or sanctioned jurisdiction	These declines follow compliance policy and cannot be overridden

A few additional defaults worth noting:

• ATM withdrawals are disabled by default and enabled per program.
• Quasi-cash and certain money-transfer categories are restricted by default.
• 3D Secure (3DS): a failed 3DS verification can result in a decline. See 3D Secure (3DS).
• Address Verification (AVS): AVS is supported and configurable per card; mismatches can contribute to a decline.

Standard decline reasons

These are the complete set of declinedReason values Rain sends when the decline originates from a Rain rule, limit, or risk check. Match on these strings:

Decline reason
account credit limit exceeded
balance inquiry not permitted
blocked entity
blocked mcc
blocked merchant
card canceled
card locked
card not activated
card spending limit exceeded
cvv mismatch
expiry mismatch
invalid pin
invalid pin attempt limit exceeded
issuer unavailable
merchant scope mismatch
restricted country
scoped daily spend limit exceeded
scoped card expired
scoped card mcc not allowed
transaction declined by risk rules
transaction declined by rules
webhook declined
webhook timeout

Processor-originated reasons

When the decline originates at the card processor, declinedReason carries a normalized description of the processor’s reason instead of one of the standard values above. Because those descriptions are configured at the processor and can change, the table below is a non-exhaustive list of examples, not a fixed enumeration. Do not branch business logic on these strings.

Reason	Description
Invalid PAN	Transaction received from a PAN that wasn’t issued by our system
Wrong PIN	Incorrect PIN entered
Invalid CVV	CVV verification failed
Invalid ARQC	Application Request Cryptogram validation failed
Invalid AAV	Application Authentication Value validation failed
Card Expired	Wrong expiry date or transaction received from an expired card
Wrong ATC	Application Transaction Counter mismatch
Invalid Service Code	Service code doesn’t match expected value
Non-ATM Withdrawal	Withdrawal request other than from an ATM
Card Status	The status of the card has been set to other than active (lost card, void, notActivated, etc.)
Account Status	The status of the account linked to the card is suspended or inactive
Blacklisted Country	Transaction from a blacklisted country
Data Contradiction	A data element defined in the document contradicts the txn request received
Card/Client Rules	Rules defined for the card/client to decline for certain cases, like declining all e-commerce, ATMs etc.
Amount Limit	Declining transactions exceeding a certain amount limit
Scoped Daily Spend Limit	Authorization on a scoped card declined because the user’s 24-hour spend across their scoped cards would exceed the configured daily limit (default: $5,000)
Online PIN Limit	Online PIN tries exceeded
Offline PIN Limit	Offline PIN tries exceeded
PIN Change Mismatch	PIN mismatch in a PIN change request
AVS Failure	Address Verification Service check failed
3DS Failure	3DS verification failed
Cashback Unsupported	Cashback request received from a POS that doesn’t support the cashback feature
E-commerce Flag	Card flag set to decline all e-commerce transactions
ATM Cash Flag	Card flag set to decline all ATM cash transactions
Balance Enquiry Flag	Card flag set to decline Balance enquiry over auth
Suspicious Transaction	Transaction flagged as potentially fraudulent due to repeated failed attempts from the same merchant

What’s next

Transaction events

See the spend webhook payloads where the declinedReason field appears.

Authorization, declines & risk rules

Review the authorization codes and risk rules that can trigger a decline.