Credit card error and declined messages

Understand the credit card error and declined messages.

Various errors can occur when conducting transactions with a credit card, leading to unsuccessful payments. One of the most common issues is a declined transaction, which can happen for multiple reasons, such as insufficient funds, incorrect card details, or suspicion of fraudulent activity. The document below details the error codes associated with transactions using a credit card saved in the payment source, including a specific example of a declined message attributed to fraud. Understanding these error codes and messages can help diagnose the cause of the decline and resolve the issue effectively.

The example below indicates a situation where a transaction has been declined due to being identified as fraudulent. The JSON structure breaks down as follows:

• detailserrors: The root element that contains details about the error.

• error: An array that encapsulates the error details. This array could potentially contain multiple error objects, but in this example, it contains one.

  • relation: A URL provided for developers, pointing to relevant documentation or resources related to the error (https://developers.digitalriver.com/v1/shoppers/SubmitCartResource).

  • code: The general classification of the error (declined), indicating the transaction was not approved.

  • subcode: Provides more specific reasoning for the error (fraud_block), indicating that the decline was due to a suspicion of fraud.

  • description: A human-readable explanation of the error, clarifying that Digital River has tagged the transaction as fraudulent.

  • declinedMessage: Contains detailed indicators of the type and nature of the decline.

    • merchantDeclinedType and customerDeclinedType: Both are set to Hard, indicating that the decline is definitive and not subject to reevaluation or simple correction.

    • code: An error code specific to this type of decline (7011), which could be used for troubleshooting or documentation to specify this scenario.

    This example is a practical illustration of how a declined payment due to fraud might be conveyed in a JSON structure, providing both general and specific information about the error aimed at aiding developers and merchants in diagnosing payment issues. See the Declined messages topic for more details.

"errors": {
    "error": [
        {
            "relation": "https://developers.digitalriver.com/v1/shoppers/SubmitCartResource",
            "code": "declined",
            "subcode": "fraud_block",
            "description": "The transaction has been identified by Digital River as fraudulent.",
            "declinedMessage": {
                "merchantDeclinedType": "Hard",
                "customerDeclinedType": "Hard",
                "code": "7011"
            }
        }
    ]
}

Credit card error codes

Understanding credit card error codes is crucial for merchants and customers to diagnose and resolve payment issues effectively. These codes are returned by the payment processor or the issuing bank when a transaction fails. The reasons for failure can range from insufficient funds or an expired card to more complex issues like fraud suspicion or the need for authentication. This section provides a comprehensive list of error codes associated with transactions using a credit card saved in the payment source. This knowledge will help identify the reason for a declined transaction, enabling a quicker resolution.

declined

The declined error code indicates that a transaction was not processed successfully. This can occur for various reasons, and understanding the subcode associated with a declined transaction can help diagnose the issue. Below are some of the subcodes related to a declined transaction:

• account_frozen: The account is frozen.

• account_closed: The account is closed.

• authentication_required: The transaction requires authentication.

• blacklisted_card: The credit card is blocklisted.

• card_limit_exceeded: The transaction exceeds the card's limit amount.

• card_not_active: The card is not active yet.

• card_type_block: The merchant has blocked this card type.

• card_velocity_exceeded: The transaction exceeds the velocity amount.

• declined: The card has been declined for an unknown reason.

• declined_can_retry: The card has been declined for an unknown reason.

• do_not_honor: The card issuing bank has declined this payment.

• duplicate_transaction: The transaction is a duplicate.

• fraud: Indicates the transaction is identified as fraudulent for one of the following reasons:

  • The issuing bank has identified the transaction as fraudulent.

  • The transaction has been identified as fraudulent.

• fraud_block: Digital River has identified the transaction as fraudulent.

• illegal_action: The transaction has been identified as illegal.

• insufficient_funds: The card has insufficient funds to complete the purchase.

• invalid_amount: The card network does not accept the amount.

• invalid_currency: The currency is not supported.

• invalid_field_data: The transaction contains invalid data.

• invalid_merchant: The merchant is invalid for this type of transaction.

• invalid_payment_method: The payment method used is invalid.

• invalid_security_field: The transaction contains invalid data.

• invalid_transaction_type: The transaction type is invalid.

• issuer_unavailable: The card does not have an issuer.

• limit_exceeded: The transaction amount exceeds the assigned limit.

• lost_stolen_card: The card is marked as lost or stolen by the issuing bank.

• mid_limit_exceeded: The transaction amount exceeds the limit for this MID.

• new_card_issued: New account information is available.

• no_response: The payment processor did not respond.

• pin_try_exceeded: The allowable number of PIN tries has been exceeded.

• restricted_card: The use of this card is restricted by the card network.

• sca_not_completed: The shopper did not complete the authentication process, so payment authorization was not initiated.

• stop_recurring: Stop all billing as this account is closed.

• suspected_fraud: The transaction is potentially identified as fraudulent.

• unidentified_error: The card has been declined for an unknown reason.

declined - contact bank

The declined - contact bank error code indicates that the card issuer requires the cardholder to contact the bank directly for further verification or approval of the transaction. This could be due to a variety of reasons, including but not limited to:

• Suspicion of fraudulent activity

• Unusual transaction patterns

• Validation of cardholder identity

Subcodes

• voice_authorization_required: The issuer requires voice authorization, indicating a need for additional verbal confirmation from the cardholder to proceed with the transaction.

invalid

The invalid error code signifies an issue with the legitimacy or acceptability of the transaction attempt due to various potential reasons. This can arise when certain elements of the transaction or the card information itself do not align with the expectations or records of the card network or issuer.

Subcodes

• issuer_invalid_card: Indicates that the card in question does not exist according to the issuer’s records, suggesting either an erroneous entry or a fraudulent attempt.

See the invalid card topic for related error codes.

invalid card

The invalid card error code is a specific category under the broader range of invalid error codes, pinpointing issues directly linked to the physical card or the accuracy of its details. Transactions can be flagged with an invalid card error for various reasons, which are enumerated as subcodes to guide in diagnosing the precise cause of the issue.

Subcodes

• card_expired – Indicates that the card has surpassed its validity period.

• invalid_address – The billing address provided does not match the one on file with the card network.

• invalid_card_number – The card number entered does not comply with standard numerical formats or the issuing network's records.

• invalid_card_bin – The card's Bank Identification Number (BIN) is not recognized.

• invalid_expiration_date – The card is expired, or the entered expiration date is incorrect.

• invalid_pin – The Personal Identification Number (PIN) entered is either incorrect or invalid.

• invalid_security_code – The card's security code (CVV/CVC) does not match the issuer's records.

• issuer_not_found – The transaction was made with a card whose issuer cannot be identified or does not exist.

For transactions marked with an invalid card error, careful review of the specific subcode is essential for understanding the root cause and determining the appropriate corrective action.

Declined messages

A declined message is generated when a transaction is attempted but cannot be completed due to various issues with the card or card's issuer. Declined messages serve as a critical communication tool, explaining why a transaction couldn't be processed. This feedback is vital for merchants and customers to understand the problem's nature of the problem and take the necessary steps to resolve it. Below, we outline the structure and common reasons behind declined messages, helping to demystify the process and enhance the transaction experience.

declinedMessage

A declinedMessage includes the following information:

• code–This code helps to categorize failure reasons for the declined message that look different but point to the same issue.

• merchantDeclinedType–This field indicates the authentication decline type of transaction initiated by the merchant.

• customerDeclinedType–This field indicates the authentication decline type of transaction initiated by the shopper.

Resolving credit card declined messages

When a shopper encounters a declined credit card transaction, they can follow these steps to address the issue:

1. Check the card details: Ensure the card number, expiration date, CVV, and billing address are entered correctly. Typos are a common issue.

2. Understand the decline code: Refer to the declined message code. This will help you identify the reason for the decline, such as insufficient funds or a blocked card.

3. Contact the card issuer: If the reason is unclear, the cardholder should contact their bank or card issuer. The issue may be related to the card's security settings or account status.

4. Try alternative payment methods: If the problem persists, consider using a different credit card or payment method altogether.

5. Update the payment information: If the card has expired or been replaced, updating the payment information with the new card details may resolve the issue.

6. Merchant verification: Merchants should follow all processing requirements set by their payment gateway and card networks.

Addressing declined messages promptly improves the transaction experience for merchants and customers, reducing frustration and enhancing payment security.