> ## Documentation Index > Fetch the complete documentation index at: https://docs.reap.global/llms.txt > Use this file to discover all available pages before exploring further. # Decline Reasons > Reference for every code that can appear on a declined card transaction. When a transaction has `status: DECLINED`, the response carries a `declineReason` object that explains why. ```json theme={null} { "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](/transactions/lifecycle#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](/transactions/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](/transactions/external-authorization/overview) 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](/spend-policies/overview) 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](/spend-policies/control-types#merchant-restriction) blocks this merchant, category, or country. | | `CHANNEL_NOT_ALLOWED` | A [channel restriction](/spend-policies/control-types#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-policies/control-types#transaction-amount-limit). | | `SPEND_LIMIT_EXCEEDED` | The transaction would push spend past a [spend limit](/spend-policies/control-types#spend-limit) for the current window. | | `AUTHORIZATION_COUNT_LIMIT_EXCEEDED` | The [transaction-count limit](/spend-policies/control-types#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](/program-configuration/funding-models#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](/transactions/external-authorization/overview) 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.