Overview

Dodo Payments API provides detailed transaction failure reasons to help you understand why a payment attempt was unsuccessful. These failure reasons are standardized across different payment methods and providers, making it easier to implement consistent error handling in your application.

Each transaction failure response includes:

  • A specific failure reason code
  • A human-readable error message
  • Additional context about the failure when available
  • Whether the error is user-correctable or requires system intervention

Understanding these failure reasons is crucial for:

  • Providing clear feedback to your customers
  • Implementing appropriate retry logic
  • Handling different failure scenarios gracefully
  • Maintaining a reliable payment processing system

Transaction Failure Reasons

The following table lists all possible transaction failure reasons, their meanings, and whether they are user-correctable errors.

Failure CodeUser ErrorDescription
AUTHENTICATION_FAILUREYesThe authentication process failed during the transaction
AUTHENTICATION_REQUIREDYesAdditional authentication is needed to complete the transaction
AUTHENTICATION_TIMEOUTYesThe authentication process timed out
CARD_DECLINEDNoThe card was declined by the issuing bank
CARD_VELOCITY_EXCEEDEDYesToo many transactions attempted in a short period
CUSTOMER_CANCELLEDYesThe customer cancelled the transaction
DO_NOT_HONORNoThe issuing bank declined the transaction
EXPIRED_CARDYesThe card has expired
FRAUDULENTYesThe transaction was flagged as potentially fraudulent
GENERIC_DECLINENoThe transaction was declined for an unspecified reason
INCORRECT_CVCYesThe provided CVC code was incorrect
INCORRECT_NUMBERYesThe card number was entered incorrectly
INSUFFICIENT_FUNDSYesThe account has insufficient funds to complete the transaction
INVALID_ACCOUNTYesThe account details provided are invalid
INVALID_AMOUNTYesThe transaction amount is invalid
INVALID_CARD_NUMBERYesThe card number format is invalid
INVALID_CARD_OWNERYesThe card owner information is invalid
INVALID_CVCYesThe CVC format is invalid
INVALID_EXPIRY_YEARYesThe card expiry year is invalid
INVALID_PINYesThe provided PIN is incorrect
INVALID_REQUESTYesThe transaction request contains invalid data
INVALID_UPI_IDYesThe UPI ID provided is invalid
LIVE_MODE_TEST_CARDYesA test card was used in live mode
LOST_CARDYesThe card has been reported as lost
MANDATE_INVALIDYesThe payment mandate is invalid
MANDATE_REQUIREDYesA mandate is required for this transaction
MANDATE_REQUIRED_SYSTEMNoSystem requires a mandate for this transaction type
NETWORK_ERRORNoA network error occurred during the transaction
NETWORK_TIMEOUTNoThe network request timed out
ORDER_CREATION_FAILEDNoFailed to create the order for the transaction
PAYMENT_METHOD_UNSUPPORTEDYesThe payment method is not supported for this transaction
PICKUP_CARDYesThe card has been reported as stolen and should be picked up
PROCESSING_ERRORNoAn error occurred while processing the transaction
REENTER_TRANSACTIONYesThe transaction needs to be re-entered
REVOCATION_OF_AUTHORIZATIONYesThe authorization for the transaction was revoked
STOLEN_CARDYesThe card has been reported as stolen
TRANSACTION_NOT_ALLOWEDYesThe transaction is not allowed for this card or account
TRANSACTION_NOT_APPROVEDYesThe transaction was not approved
TRY_AGAIN_LATERNoThe transaction should be retried later
UNKNOWN_ERRORNoAn unknown error occurred
PAYMENT_METHOD_PROVIDER_DECLINEDYesThe payment method provider declined the transaction

User Error indicates whether the payment decline can be resolved by the customer. When true, the customer can take action to fix the issue (e.g., entering correct card details). When false, the decline is due to system-level issues or bank restrictions that cannot be resolved by the customer.

Support

For additional help with transaction failures or integration issues, please contact our support team at support@dodopayments.com.