Card declines and error codes

When a customer's credit or debit card transaction is declined, it can be frustrating for both the customer and the merchant. At Xendit, we've optimized our system to minimize declines originating from the acquiring bank. This means most declines you encounter are likely due to the issuing bank—the bank that issued the customer's card.

Why Do Declines Happen?

Issuing banks are the primary source of decline information, but they only share the exact reason directly with the cardholder. To get details, the cardholder must contact their bank, providing transaction specifics like the amount and date.

Since asking every customer to call their bank isn't practical, Xendit uses heuristics. These are intelligent estimates based on signals from the issuing bank and regional factors, helping us determine the most probable reasons for declines. These insights are available in the Decline Insights section of the Card Transaction Details page in your Xendit Dashboard.

Xendit decline reasons and network response codes

For a comprehensive list of Xendit's specific error and failure codes, please refer to this page.

In addition to Xendit's codes, card networks also return their own error codes. These are provided as additional data in our API responses, giving you more granular information about a decline.

Here's an example of a network 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 - The transStatus result, directly from the 3DS2 response, indicating the authentication status of the transaction.

• three_ds_flow - The 3DS2 authentication flow the customer experienced when completing 3DS2.

Card network response codes

TransStatus (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.

Possible values:

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

Possible values:

Mastercard Merchant Advice Codes

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

How to use Mastercard merchant advice codes:

• Identify the 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.

• 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.

• Avoid Penalties: Codes may warn of penalties for retrying certain transactions.

  • Example: Code 21 — Don't retry, penalty fees may apply.

• 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.

• 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.

Possible values: