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:

"payment_details": {
    //payment detail fields
    "authorization_data": {
        "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.

A Mastercard merchant advice code will usually come in combination with one of the following card_network_response_code codes: 14, 41, 43, 54, 57, 62, 65, 75, 82, 83, 85, 91, 93 and 96 (explained in the overview).

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:

Card network response code overview (card_network_response_code)

Handling 3DS Response Details: Three DS transaction status reason & Three DS challenge cancel code

When a 3DS authentication completes, your integration receives a primary three_ds_trans_status (Transaction Status) code from the authentication webhook event. While codes like Y (Success) are simple, handling failures (N, U, or R) requires more detail.

This is where three_ds_trans_status_reason and three_ds_challenge_cancel_code become essential. They provide the specific "why" behind a failed or incomplete authentication, allowing you to build a robust handler, debug issues, and provide clear feedback to your users.

Three DS trans status reason (three_ds_trans_status_reason)

This is the primary reason code for the authentication outcome. It's sent by the issuer's bank (the ACS) and explains why the transaction received its final three_ds_trans_status.

You should always check this parameter when the three_ds_trans_status is:

• N (Not Authenticated)

• U (Unable to Authenticate)

• R (Rejected by Issuer)

The detail of the three_ds_trans_status_reason can be seen in this table below

Challenge Cancel Code (three_ds_challenge_cancel_code)

This parameter is more specific. It only applies if a challenge was presented and then cancelled. It tells you why the challenge window was dismissed.

You should check this parameter if three_ds_trans_status is N and three_ds_trans_status_reason is 26 (Authentication Not Performed). This combination gives you the full story.

Implementing Your Response Handler (Putting It Together)

Use this logic as a starting point for your server-side handler.

Example Scenario

A shopper is presented with a 3DS challenge. They get confused and click the "Cancel" button.

Here is the data your server will likely receive:

• three_ds_trans_status: N (Not Authenticated)

• three_ds_trans_status_reason: 26 (Authentication Not Performed)

• three_ds_challenge_cancel_code: 01 (Cardholder Selected "Cancel")

This structure allows you to properly handle failures, provide clear feedback, and maintain excellent logs for debugging.

The detail of the three_ds_challenge_cancel_code can be seen in this table below