Decline Reasons - Reap API

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 at this point of sale.
`ATM_COUNTRY_RESTRICTED`	ATM withdrawals are restricted in the country where the cardholder is attempting the withdrawal.
`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.

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.

​Cardholder can self-resolve

​Network-mandated limits

​Merchant or transaction restriction

​Requires support or program action

​Security

​Catch-all