Card Decline and Error Codes

code	description	source
card_declined	Issuer declined the transaction without providing specific reason.	issuer
incorrect_number	Card number is incorrect or invalid. Check for typos or formatting issues.	issuer
expired_card	Card is expired and cannot be used for transactions.	issuer
invalid_cvc	Card security code (CVC/CVV) is invalid. Ensure the code matches the back of the card.	issuer
incorrect_zip	ZIP or postal code verification failed. Address may not match bank records.	issuer
incorrect_expiry	Invalid expiration date format or mismatch.	issuer
insufficient_funds	Not enough balance on the card to complete the transaction.	issuer
do_not_honor	Issuer refused the transaction, often for unspecified security or policy reasons.	issuer
lost_or_stolen	Card reported as lost or stolen — blocked for all transactions.	issuer
restricted_card	Card is not allowed for this type of transaction or merchant.	issuer
processing_not_allowed	Issuer blocked this transaction. May be due to region, merchant type or amount.	issuer
issuer_unavailable	Could not reach the card issuer to authorize the transaction.	issuer
network_unavailable	Card network (Visa, Mastercard, etc.) is currently unavailable.	network
authorization_timeout	Issuer did not respond in time. Could be due to network issues or issuer latency.	issuer
fraud_suspected	Transaction flagged as suspicious by fraud rules (e.g. IP, amount, velocity).	fraud_system
blocked_by_risk	Transaction blocked by internal risk engine for policy violation or pattern detection.	fraud_system
velocity_limit_exceeded	Too many attempts in a short period — velocity rule triggered.	fraud_system
invalid_amount	Invalid transaction amount, such as negative or improperly formatted values.	validation
invalid_currency	Unsupported or unrecognized currency for the transaction.	validation
invalid_card_type	Card type (e.g. prepaid, corporate) not supported by this merchant or processor.	validation
missing_fields	Required fields are missing in the transaction request (e.g. expiry, CVC, amount).	validation
invalid_merchant	Merchant account is invalid, inactive, or misconfigured.	unknown
provider_timeout	Timeout occurred while waiting for response from payment provider.	integration
provider_down	Payment provider is currently unavailable or experiencing downtime.	integration
duplicate_transaction	Duplicate transaction detected — same amount, card, and timestamp.	integration
internal_error	Unexpected error in the internal payment system logic.	internal
invalid_signature	Invalid signature in webhook or callback — possible tampering detected.	internal
unknown_error	An unknown or unclassified error occurred.	integration
invalid_document	Invalid document number — expected a valid CPF or CNPJ.	internal
merchant_blocked	Transaction declined because the merchant is blocked from processing payments.	internal
fallback_required	Insert card — contactless (NFC) not allowed for this transaction or exceeded limit.	terminal
card_not_detected	Card could not be read — ensure it is inserted, tapped, or swiped properly.	terminal
use_chip	Card requires chip insertion due to contactless attempt limit.	terminal
remove_card	Please remove the card from the terminal to proceed.	terminal
insert_or_swipe	Insert or swipe the card to start the transaction.	terminal
signature_required	Transaction requires signature instead of PIN or contactless confirmation.	terminal
pin_required	PIN entry is required but was not provided. Prompt the user to enter their PIN.	terminal
country_restricted	Transactions from this country or to this merchant are restricted.	fraud_system
blocked_bin	Card BIN (Bank Identification Number) is blocked due to risk or policy rules.	fraud_system
mcc_blocked	Merchant Category Code is restricted — cardholder cannot transact with this type of business.	fraud_system
suspicious_location	Transaction blocked due to unusual or high-risk location.	unknown
acquirer_unavailable	Acquirer bank or processor is currently unavailable.	acquirer
acquirer_decline	Transaction was declined by the acquiring bank.	acquirer
invalid_mid	Invalid or unregistered Merchant ID (MID).	acquirer
invalid_terminal	Terminal not registered or authorized with the acquirer.	acquirer
invalid_cvv_format	The CVV code format is invalid — may contain letters or incorrect length.	unknown
card_inactive	Card is inactive or not yet activated by the cardholder.	unknown
card_not_personalized	Card is not yet ready for transactions — possibly unissued or system error.	unknown
manual_review_required	Transaction is being held for manual review by the risk team.	fraud_system
unexpected_card_type	Card type was not expected for this transaction — check acceptance settings.	validation
retry_transaction	Temporary issue occurred — ask the user to retry the transaction.	integration
fallback_error	Fallback transaction (after chip/contactless failure) was unsuccessful.	unknown
reversal_in_progress	The original transaction is being reversed — wait for final status.	reversal
refund_in_process	Refund already initiated — cannot process duplicate refund.	reversal
chargeback_pending	Transaction is under chargeback investigation.	reversal
browser_not_supported	User browser does not support payment method (e.g., Apple Pay, 3DS).	user
user_abandoned	User closed or abandoned the payment before completing.	user
session_expired	Payment session expired — reload or try again.	integration
invalid_token	Authentication token is missing or invalid.	internal
invalid_request_format	Request body is invalid or not in expected format.	internal
webhook_failed	Webhook could not be delivered or was rejected.	integration
account_closed	Account is closed and can no longer be used.	issuer
account_inactive	Account is inactive or frozen.	issuer
debit_not_allowed	Debit transactions are not allowed with this card. Consider switching to credit.	issuer
credit_not_allowed	Credit transactions are not allowed with this card. Try a debit method.	issuer
cashback_not_allowed	Cashback is not supported for this card or merchant.	unknown
amount_too_high	Transaction amount exceeds the allowed maximum. Try a lower amount.	validation
amount_too_low	Transaction amount is below the minimum required. Increase the value to continue.	validation
user_blacklisted	User is blocked due to prior fraud or abuse activity.	fraud_system
email_blocked	Email address has been flagged due to past suspicious activity.	fraud_system
installment_not_supported	Installment payments are not supported for this card or merchant.	validation
no_carrier_signal	POS terminal has lost its network connection — check connectivity.	terminal
device_error	Card reader or terminal hardware failure — please restart the device.	terminal
keypad_failure	PIN pad malfunction — unable to collect input.	terminal
kyc_required	User must complete identity verification before transacting.	fraud_system
document_mismatch	Provided document does not match the user registered identity.	fraud_system
max_retry_exceeded	Too many retry attempts — transaction blocked for security.	fraud_system
locked_for_retry	Transaction temporarily locked due to previous failures. Please wait before retrying.	fraud_system
cashback_not_allowed	Cashback is not supported for this card or merchant.	issuer
email_blocked	Email address has been flagged due to past suspicious activity.	fraud_system
locked_for_retry	Transaction temporarily locked due to previous failures. Please wait before retrying.	fraud_system
invalid_customer	Customer ID is invalid or not found in the system.	internal