Decline Reasons

When a transaction has status: DECLINED, the response carries a declineReason object that explains why.

{
  "status": "DECLINED",
  "declineReason": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance for this transaction."
  }
}

code is for your integration; message is for the cardholder.

code is a machine-readable identifier intended for your backend logic - branching on it to route the cardholder to a top-up screen, prompt for a PIN re-entry, surface a “card blocked” support flow, and so on. Do not render the code string itself to end users.
message is human-readable English copy safe to display directly to the cardholder as a sensible default. You can also write your own copy keyed off code whenever you want fuller control over UX.

This page groups every code that can appear in declineReason.code by what your integration or the cardholder can do about it. For lifecycle context (when a decline is recorded, what webhook fires) see Decline at authorization.

Cardholder can self-resolve

The cardholder can take an action and retry.

Code	When it happens	Suggested next step
`INSUFFICIENT_BALANCE`	The account’s available balance is below the transaction amount.	Prompt the cardholder to top up, then retry.
`CARD_FROZEN`	The card is in `FROZEN` status.	Unfreeze the card from your app (or have the cardholder do it) and retry.
`CARD_NOT_ACTIVATED`	The card was issued but never activated.	Activate the card, then retry.
`INCORRECT_PIN`	The PIN entered at the terminal could not be verified. Covers both wrong PIN and PIN verification failures from the network.	Cardholder retries with the correct PIN.
`INCORRECT_CVV`	The CVV entered at checkout was wrong.	Cardholder checks and retries.
`INVALID_CARD_DETAILS`	One or more of the card details (PAN, expiry, CVV) did not match.	Cardholder rechecks the card details and retries.
`CONTACTLESS_NOT_SUPPORTED`	The contactless tap could not be processed.	Cardholder inserts or swipes the card instead.
`TERMINAL_ERROR`	The terminal could not complete the transaction.	Cardholder retries at the same or a different terminal.
`CASH_SERVICE_NOT_AVAILABLE`	The ATM is not providing cash service at the moment.	Cardholder tries a different ATM.

Network-mandated limits

The transaction exceeded a limit enforced by the platform. Trying a smaller amount or waiting for the limit window to reset usually resolves it.

Code	When it happens
`ATM_WITHDRAWAL_LIMIT_EXCEEDED`	The per-window ATM amount cap has been exceeded.
`ATM_WITHDRAWAL_FREQUENCY_EXCEEDED`	The maximum number of ATM withdrawals allowed in the current window has been reached.

Merchant or transaction restriction

The card cannot be used for this particular transaction. The cardholder should use a different payment method or merchant; retrying the same flow will not help.

Code	When it happens
`MERCHANT_CARD_TYPE_MISMATCH`	The merchant does not accept this card brand or product type.
`MERCHANT_CATEGORY_CODE_NOT_ALLOWED`	The merchant’s category (MCC) is restricted. See Restricted MCCs.
`TRANSACTION_TYPE_NOT_ALLOWED`	The card cannot be used for this transaction type.
`TRANSACTION_NOT_ALLOWED`	Your own authorization endpoint declined the transaction on your controls. External authorization projects only; it is the verbatim reason your endpoint returned.
`WITHDRAWALS_NOT_ALLOWED`	Cash withdrawals are not enabled on this card.
`NETWORK_DECLINE`	Generic decline returned by the card network (Visa) without a more specific reason. Cardholder can retry or use a different payment method.

Spending policy controls

The transaction was blocked by a spend policy you configured. The declined transaction also carries a policy reference naming the exact policy responsible, so you can tell which rule fired. Retrying the same transaction will not help until the limit window resets or the policy is changed.

Code	When it happens
`MERCHANT_NOT_ALLOWED`	A merchant restriction blocks this merchant, category, or country.
`CHANNEL_NOT_ALLOWED`	A channel restriction blocks this channel (in-store, online, ATM, or push-to-card).
`TRANSACTION_AMOUNT_LIMIT_EXCEEDED`	The transaction is above the per-transaction limit.
`SPEND_LIMIT_EXCEEDED`	The transaction would push spend past a spend limit for the current window.
`AUTHORIZATION_COUNT_LIMIT_EXCEEDED`	The transaction-count limit for the current window has been reached.

Requires support or program action

The card or account is in a state that the cardholder cannot resolve themselves - your team needs to act, or the cardholder needs to contact support.

Code	When it happens	What to do
`CARD_NOT_ACTIVE`	The card has been deactivated or is otherwise not in an active status.	Check the card status via the API. Issue a replacement if the card has been permanently deactivated.
`CARD_EXPIRED`	The card has passed its expiry date.	Issue a replacement card.
`CARD_BLOCKED`	The card has been blocked. Covers manual blocks as well as auto-blocks from repeated incorrect PIN, CVV, or expiry-date entries.	The cardholder must contact support to unblock.
`CARD_REPORTED_LOST`	The card has been reported lost.	The cardholder requests a replacement card.
`CARD_REPORTED_STOLEN`	The card has been reported stolen.	The cardholder requests a replacement card.
`ACCOUNT_NOT_ACTIVE`	The account linked to the card is not active.	Check the account status. A `RESTRICTED` account typically reflects a compliance issue that needs to be resolved.
`INSUFFICIENT_MASTER_BALANCE`	The master collateral account does not have enough balance to authorize the transaction. The cardholder’s own balance is fine; the program-level collateral is the limiting factor. Specific to Program-Funded programs.	Top up the master collateral account, then retry.

Security

Code	When it happens	What to do
`SUSPECTED_FRAUD`	The transaction was declined for security reasons by Reap, the card network, or our fraud-detection partners.	The cardholder can retry or contact support if they believe the decline was wrong. Persistent suspected-fraud declines on the same card may warrant proactive review.

Catch-all

Code	When it happens
`INTERNAL_ERROR`	A bucket reason returned when the transaction could not be authorized due to an underlying system error.

If you need the underlying reason for a specific transaction that came back as INTERNAL_ERROR, contact Reap support with the transaction ID. In External authorization projects, INTERNAL_ERROR is also what the cardholder sees when your authorization endpoint does not respond in time or returns an invalid response. Reap fails closed and records the underlying cause on its side.

Getting Started

Program Configuration

Compliance

Accounts

Cards

Transactions

Spend Policies

Virtual Assets

Cardholder can self-resolve

Network-mandated limits

Merchant or transaction restriction

Spending policy controls

Requires support or program action

Security

Catch-all

​Cardholder can self-resolve

​Network-mandated limits

​Merchant or transaction restriction

​Spending policy controls

​Requires support or program action

​Security

​Catch-all

Cardholder can self-resolve

Network-mandated limits

Merchant or transaction restriction

Spending policy controls

Requires support or program action

Security

Catch-all