Skip to main content

​
Card Decline Codes System

This document defines our standardized internal decline code system designed to unify error handling across all integrated Payment Service Providers (PSPs) and acquirers. The system follows industry best practices for payment processing error categorization.

​
Code Structure

Structure of Decline Codes: Format: [Category][Type][Sequence]
  • Category: Single letter (A-Z) representing the error category.
  • Type: H (Hard decline - permanent failure) or S (Soft decline - retry allowed).
  • Sequence: Two digits (01-99) for specific errors within the category.

​
Decline Codes

Decline codes are organized into categories based on the nature of the error:

​
A - Authentication & Security

CodeTypeDescriptionCustomer Message
AH01HardInvalid card numberPlease check your card number and try again.
AH02HardInvalid CVV/CVCPlease check your security code and try again.
AH03HardInvalid expiry datePlease check your card’s expiry date and try again.
AH04Hard3D Secure authentication failedPayment authentication failed. Please try again or use a different payment method.
AH05HardFraudulent transaction detectedThis transaction cannot be processed. Please contact your bank.
AH06HardCard reported lostThis card has been reported lost. Please use a different payment method.
AH07HardCard reported stolenThis card has been reported stolen. Please use a different payment method.
AH08HardSuspicious behavior detectedThis transaction appears suspicious and cannot be processed.
AS01Soft3D Secure authentication requiredAdditional authentication is required. Please complete the verification process.
AS02SoftStrong customer authentication (SCA) requiredAdditional customer authentication is required by your bank.

​
B - Bank/Issuer Issues

CodeTypeDescriptionCustomer Message
BH01HardCard declined by bankYour card was declined by your bank. Please contact your bank or use a different payment method.
BH02HardCard expiredYour card has expired. Please use a different payment method.
BH03HardCard canceled/disabledThis card is no longer active. Please use a different payment method.
BH04HardCard restrictedYour card has been restricted. Please contact your bank.
BH05HardBank authorization requiredYour bank requires additional authorization for this transaction.
BH06HardCard blacklistedThis card cannot be used for payments. Please use a different payment method.
BH07HardInvalid accountThe account associated with this card is invalid. Please use a different payment method.
BH08HardBank requested card retentionYour bank has requested this card be retained. Please contact your bank.
BS01SoftBank temporarily unavailableYour bank’s system is temporarily unavailable. Please try again later.
BS02SoftIssuer system maintenanceYour bank’s system is under maintenance. Please try again later.

​
C - Credit/Funds Issues

CodeTypeDescriptionCustomer Message
CH01HardInsufficient fundsYour card has insufficient funds for this transaction.
CH02HardCredit limit exceededThis transaction exceeds your card’s credit limit.
CH03HardOver limitYour card is over its limit. Please use a different payment method.
CH04HardWithdrawal limit exceededThis transaction exceeds your withdrawal limit.
CH05HardTransaction limit exceededThis transaction exceeds your card’s transaction limit.
CS01SoftTemporary credit holdThere’s a temporary hold on your account. Please try again later.

​
D - Data/Configuration Issues

CodeTypeDescriptionCustomer Message
DH01HardInvalid merchant configurationWe’re unable to process this payment. Please contact customer service.
DH02HardCurrency not supportedThis currency is not supported. Please try a different payment method.
DH03HardCard type not supportedThis card type is not supported for this transaction.
DH04HardInvalid amountThe transaction amount is invalid.
DH05HardTransaction type not permittedThis type of transaction is not permitted with your card.
DH06HardInvalid transaction dataInvalid transaction information. Please try again.
DS01SoftValidation error - retry allowedThere was a validation error. Please try again.
DS02SoftConfiguration temporarily unavailablePayment processing is temporarily unavailable. Please try again later.

​
E - External/Network Issues

CodeTypeDescriptionCustomer Message
ES01SoftNetwork timeoutConnection timeout occurred. Please try again.
ES02SoftCommunication errorCommunication error occurred. Please try again.
ES03SoftProcessor unavailablePayment processor is temporarily unavailable. Please try again later.
ES04SoftGateway timeoutPayment gateway timeout. Please try again.
ES05SoftExternal service errorExternal service error. Please try again later.

​
F - Fraud Prevention

CodeTypeDescriptionCustomer Message
FH01HardHigh risk transaction blockedThis transaction has been blocked for security reasons.
FH02HardVelocity rules violatedToo many transactions in a short period. Please try again later.
FH03HardGeographic restrictionsThis transaction is not allowed from your location.
FH04HardMerchant blacklist matchThis transaction cannot be processed.
FH05HardCard blocked for fraudYour card has been blocked for security reasons. Please contact your bank.
FS01SoftTransaction under fraud reviewYour transaction is under security review. Please try again later.

​
G - General/System Issues

CodeTypeDescriptionCustomer Message
GS01SoftGeneral system errorA system error occurred. Please try again.
GS02SoftProcessing error - retry allowedA processing error occurred. Please try again.
GS03SoftDuplicate transactionThis appears to be a duplicate transaction. Please check your payment history.
GS04SoftTransaction expiredThis transaction has expired. Please start a new payment.
GS05SoftService temporarily unavailablePayment service is temporarily unavailable. Please try again later.

​
U - User/Customer Issues

CodeTypeDescriptionCustomer Message
UH01HardTransaction canceled by customerYou have canceled this transaction.
UH02HardCustomer authentication failedAuthentication failed. Please try again or contact customer service.
UH03HardCustomer verification failedIdentity verification failed. Please contact customer service.
US01SoftCustomer action requiredPlease complete the required action to proceed.
US02SoftSession timeoutYour session has expired. Please start a new payment.

​
Webhook Notification Payload Example

This is an example of a decline notification payload sent via webhook: 
{
  "id": "399f4425-67be-40ae-a3d5-42caa86dfb96",
  "operation_type": "payment",
  "amount": "500",
  "currency": "MXN",
  "client_reference": "order-credit card deposit test FTH",
  "status": "Declined",
  "decline_code": "BH01",
  "decline_reason": "Card declined by bank",
  "provider": "tonder",
  "transaction_id": "9294",
  "payment_method_type": "CARD",
  "created": "2025-10-08T19:23:13.068277Z",
  "event_type": "payment_Declined",
  "action": "MODIFY"
}

​
Test Data

To generate a decline notification, use the following details:
  • Card Number: 5555 5555 5555 4444
  • Expiration Date: Any future date
  • CVV: Any 3-digit CVV (e.g., 123)