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."
  }
}

Only message is written for the cardholder. code is for your integration.

code is a machine-readable identifier for your backend logic, monitoring, and support tooling. Branch on it to route the cardholder to a top-up screen, prompt for a PIN re-entry, surface a “card blocked” support flow, alert your on-call team, and so on. Do not show the code, or a label derived from it, to end users: some codes describe your own systems rather than anything the cardholder did.
message is plain English copy safe to show the cardholder as it is. You can also write your own copy keyed off code when you want fuller control over the experience.

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 Visa Direct).
`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 blocks you placed as well as auto-blocks from repeated incorrect PIN, CVV, or expiry-date entries.	Read `blockLiftable` on the card. When it is `true`, call unblock; when it is `false`, the block is a Reap risk or compliance decision and only Reap support can lift it. See Card statuses.
`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.

Your authorization endpoint

External authorization projects only. Reap fails closed: when your authorization endpoint does not return a valid decision, Reap declines the transaction. These codes tell you the decline came from your endpoint, so you can investigate on your side without contacting Reap support.

Code	When it happens	What to do
`AUTHORIZATION_ENDPOINT_TIMEOUT`	Your endpoint did not respond within the 1.6 second window. It may still have received the request and decided on it.	Check your endpoint’s latency for this request, and release anything you reserved for it. See Handling requests.
`AUTHORIZATION_ENDPOINT_ERROR`	Reap could not get a decision from your endpoint: it was unreachable, returned a non-`2xx` status, or returned a body Reap could not parse. Reap also returns it when your project has no active authorization webhook, or when the webhook URL resolves to an address Reap does not call, such as a private network address.	Check that an active authorization webhook is registered with a public URL, then check your endpoint’s logs and availability.

The decline carries the same transactionId and eventId Reap sent your endpoint, so you can find the request in your own logs. See Reconciliation. The cardholder message for both codes is a generic “couldn’t be completed” message that does not mention your systems.

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.

Getting Started

Program Configuration

Compliance

Accounts

Cards

Transactions

Spend Policies

Virtual Assets

Statements

Agentic Payments

Rewards

Cardholder can self-resolve

Network-mandated limits

Merchant or transaction restriction

Spending policy controls

Requires support or program action

Security

Your authorization endpoint

Catch-all

​Cardholder can self-resolve

​Network-mandated limits

​Merchant or transaction restriction

​Spending policy controls

​Requires support or program action

​Security

​Your authorization endpoint

​Catch-all

Cardholder can self-resolve

Network-mandated limits

Merchant or transaction restriction

Spending policy controls

Requires support or program action

Security

Your authorization endpoint

Catch-all