Card declines and error codes

Overview

The bank that issues a credit or debit card is called the Issuing Bank. When a customer makes a purchase, the Issuing Bank sends funds to the merchant’s Acquiring Bank, where the transaction settles. Xendit has optimized its setup with Acquiring Banks to minimize declines on their side, so most declines come from the Issuing Bank.

Issuing banks share the exact reason for a decline only with the cardholder. To get details, the cardholder must contact their bank with information like the transaction amount and date.

Since asking customers to call their bank for every decline isn't scalable, Xendit uses heuristics to estimate the most likely reasons for declines based on signals from the Issuing Bank and regional factors. These insights are available in the Decline Insights section of the Card Transaction Details page in the Xendit Dashboard.

Xendit Decline Reasons

Network response codes

In addition to Xendit error codes, networks also return error codes to Xendit.

These error codes are returned as additional data in our API responses (This will be enabled on live starting November 4 2025 - we are currently running a pilot on the test environment).

Example response:

"network_response": {
    "card_network_response_code": "65",
    "card_network_descriptor": "Exceeds withdrawal count limit",
    "merchant_advice_code": "28",
    "merchant_advice_descriptor": "Retry after 6 days",
    "three_ds_trans_status": "Y",
    "three_ds_flow": "CHALLENGE"
}

Network response code data

card_network_response_code - The response code returned by the scheme (Visa, Mastercard, JCB, China Unionpay or Amex)

card_network_descriptor - Description of the response code

merchant_advice_code - Only returned when present, only returned for Mastercard. Mastercard has codes which describe what action to take towards merchants. Not following Mastercard's advice may lead to "excessive retry fines". These fines can go up to USD 0.50 per transaction.

merchant_advice_descriptor - Only returned when present. Only returned for Mastercard. Description / action to take for the merchant advice code.

three_ds_trans_status - transStatus result, directly coming from the 3DS2 response.

three_ds_flow - When authenticated - the authentication flow this transaction has followed

Trans Status (three_ds_trans_status) and 3DS Flow (three_ds_flow)

three_ds_trans_status Indicates whether a transaction was authenticated, as per EMVCo 3DS2 specification.

The possible values are:

• Y: Authentication / Account verification successfu
• I: Authentication / Exemption granted by Issuer
• N: Not Authenticated / account not verified. Transaction denied.
• U: Authentication / account verification could not be performed (could be due to authentication not being available for the card/issuer)
• A: Authentication / verification was attempted
• C: Challenge Required. Additional authentication is required using a Challenge
• R: Authentication / account verification rejected by the Issuer.

three_ds_flow can return either FRICTIONLESS or CHALLENGE, indicating which flow the shopper has gone through when completing 3DS2.

Mastercard Merchant Advice Codes

Merchant advice codes provide guidance on handling declined transactions. These codes help developers and merchants understand why a transaction was declined and what actions to take next.

How to Use Mastercard Merchant Advice Codes:

1. Identify Decline Reason: Each code corresponds to a specific reason for decline. Use it to determine whether the issue is technical, policy-related, or cardholder-specific.
   • Example: Code 03 — Don't retry, penalty fees may apply. Consider contacting the cardholder.
2. Actionable vs. Non-actionable Codes: Some codes suggest retrying, while others require no further action.
   • Example: Code 24 — Retry after 1 hour.
     Code 40 — No action required.
3. Avoid Penalties: Codes may warn of penalties for retrying certain transactions.
   • Example: Code 21 — Don't retry, penalty fees may apply.
4. Contact Support for Technical Issues: If the code refers to technical problems, direct developers to reach out to support.
   • Example: Code 04 — Contact support for token issues.
5. Installments and Recurring Payments: Some codes indicate restrictions on specific payment types, like installments.
   • Example: Code 22 — Installments not allowed, do not retry.

By integrating these codes into your payment processing logic, you can handle declined transactions appropriately, avoid penalties, and provide better guidance to merchants.

Merchant advice code overview (merchant_advice_code)

Card network response code overview (card_network_response_code)

Last Updated on 2024-10-23