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 codemerchant_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- ThetransStatusresult, 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:
Error / response code | Description |
|---|---|
Y | Account verification successful |
I | Authentication / Exemption granted by Issuer |
N | Not Authenticated / account not verified, challenge failed |
U | Authentication / account verification could not be performed (could be due to authentication not being available for the card/issuer). Could potentially still proceed with transaction, if no 3DS is enabled |
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.
Possible values:
Value | Description |
|---|---|
FRICTIONLESS | The shopper went through a frictionless 3DS flow |
CHALLENGE | The shopper went through a challenge 3DS flow |
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:
Code | Description | Additional information |
|---|---|---|
1 | Update card information | Ask the shopper to provide new card information |
2 | Try the again payment after 72 hours. | |
3 | Do not retry this payment. Retries can be subject to penalty fees by Mastercard. Consider reaching out directly to the shopper. | |
4 | Technical token issue, reach out to Xendit support. | |
8 | Blocked by payment processor. | Contact Xendit support |
21 | Do not retry this payment. Retries can be subject to penalty fees by Mastercard. | Penalties can go up to USD$0.50 per call. |
22 | Do not retry this payment, installments not allowed for this transaction. | Installments are not supported |
24 | Retry the payment after 1 hour. | |
25 | Retry the payment after 24 hours. | |
26 | Retry the payment after 2 days. | |
27 | Retry the payment after 4 days. | |
28 | Retry the payment after 6 days. | |
29 | Retry the payment after 8 days. | |
30 | Retry the payment after 10 days. | |
40 | No action required. | |
41 | No action required. | |
42 | No action required. | |
99 | No action possible. |
Card network response code overview (card_network_response_code)
Network response code | Description | Action | Xendit mapped code | Additional information |
|---|---|---|---|---|
01 | Refer to card issuer | Recommend cardholder to contact their card issuing bank to resolve the problem on online transaction Or, try to use different card. Or, use other form of payment. | DECLINED_BY_ISSUER | |
02 | Refer to card issuer | Shopper to contact the card issuer | DECLINED_BY_ISSUER | |
03 | Invalid merchant | Reach out to Xendit | DECLINED_BY_ISSUER | |
04 | Capture card | Retain card | STOLEN_CARD | |
05 | Do not honor | Try again using a different card | DECLINED_BY_ISSUER | Often used by issuers when they don't trust a transaction or did not properly map a different error code. |
06 | Try again using a different card | Try again using a different card | DECLINED_BY_ISSUER | |
07 | Pick up card, special condition (fraud account) | - | STOLEN_CARD | Used in physical situations, telling merchants to retain the card |
10 | Partial Approval | - | PARTIAL_APPROVAL | A partial amount was accepted, the rest of the transaction needs to be completed using a different card. |
11 | Approved (V.I.P) | - | SUCCESS | Used by visa when they stand in for the issuer, accepting a transaction on behalf of. |
12 | Invalid transaction | Do not try again | INACTIVE_OR_UNAUTHORIZED_CARD | |
13 | Invalid amount | Use a different amount | INACTIVE_OR_UNAUTHORIZED_CARD | |
14 | Invalid card number | Try again with a different card (number) | INVALID_CARD | |
15 | Invalid issuer | Retry at a later time | INVALID_CARD | |
19 | Re-enter transaction | Retry the transaction | PROCESSOR_ERROR | |
21 | Payment cancellation | Do not retry | DECLINED_BY_ISSUER | The user cancelled the transaction during processing, only relevant on EDC |
25 | Unable to locate record in file | Reach out to Xendit support | PROCESSOR_ERROR | This will not occur |
28 | File temporarily not available for update or inquiry | Reach out to Xendit support | PROCESSOR_ERROR | Indicator of problems on the scheme side |
30 | Format error | The card issuer does not recognize the transaction details being entered. This is due to a format error. The shopper should check the transaction information and try again. | PROCESSOR_ERROR | |
39 | No credit account | Try again using a different card | INVALID_CVV | The card is not suitable for this type of transactino. For example when adttempting to use prepaid for recurring. |
41 | Stolen card | Do not retry | STOLEN_CARD | |
42 | Processor error | Try again in a few minutes | PROCESS_ERROR | Recommend cardholder to try again in a few minutes. Alternatively, they can try to use other form of payment. |
43 | Stolen card | Do not retry | STOLEN_CARD | |
46 | Closed account | Try again using a different card | INACTIVE_OR_UNAUTHORIZED_CARD | |
51 | Insufficient funds | INSUFFICIENT_BALANCE | ||
52 | No checking account | PROCESSOR_ERROR | ||
53 | No savings account | PROCESSOR_ERROR | ||
54 | Expired card | EXPIRED_CARD | Could also mean expiration date is missing | |
55 | Invalid PIN | INACTIVE_OR_UNAUTHORIZED_CARD | ||
57 | Transaction not permitted to cardholder | Retry with a different card | INACTIVE_OR_UNAUTHORIZED_CARD | The card is not suitable for this type of transactino. For example when adttempting to use prepaid for recurring. |
58 | Transaction not permitted | DECLINED_BY_ISSUER | ||
59 | Suspected fraud | ISSUER_SUSPECT_FRAUD | Issuer suspects fraud | |
61 | Limit exceeded | INSUFFICIENT_BALANCE | ||
62 | Restricted card | Shopper could contact issuer or use a different card | DECLINED_BY_ISSUER | Card no. valid in country or region |
63 | Security violation | DECLINED_BY_ISSUER | ||
64 | Card declined | DECLINED_BY_PROCESSOR | ||
65 | Limit exceeded | DECLINED_BY_ISSUER | ||
70 | Contact card issuer | DECLINED_BY_ISSUER | ||
71 | PIN not changed | CARD_DECLINED | Does not happen on eCommerce | |
72 | Account not yet active | Only happens for Mastercard | DECLINED_BY_ISSUER | |
74 | Invalid PIN | DECLINED_BY_PROCESSOR | ||
75 | Allowable number of PIN tries exceeded | DECLINED_BY_ISSUER | ||
78 | Invalid / nonexistent account specified (general) | INACTIVE_OR_UNAUTHORIZED_CARD | The transaction is from a new cardholder and the card has not been properly unblocked or activated. | |
79 | Life cycle | DECLINED_BY_PROCESSOR | Mastercard only | |
80 | Credit issuer unavailable | PROCESSOR_ERROR | ||
81 | Suspected fraud | DECLINED_BY_PROCESSOR | ||
82 | Invalid CVN | INVALID_CVV | Do not tell shoppers their CVN was invalid, this may help fraudsters. | |
83 | Suspected fraud | ISSUER_SUSPECT_FRAUD | ||
84 | Invalid authorization life cycle | DECLINED_BY_ISSUER | ||
85 | Approved | SUCCESS | ||
86 | Invalid PIN | DECLINED_BY_PROCESSOR | ||
87 | Purchase amount only, no cash back allowed | CARD_DECLINED | ||
88 | Cryptographic failure | CARD_DECLINED | ||
89 | Ineligible to receive financial position information (GIV) | PROCESSOR_ERROR | ||
90 | Cutoff is in progress | Retry at a later stage | CARD_DECLINED | |
91 | Temporary system error | Retry at a later stage | ISSUER_UNAVAILABLE | |
92 | Temporary system error | Retry at a later stage | INACTIVE_OR_UNAUTHORIZED_CARD | |
93 | Transaction cannot be completed - violation of law | DECLINED_BY_ISSUER | ||
94 | Duplicated transaction | Do not retry | DECLINED_BY_PROCESSOR | |
96 | System error | ISSUER_UNAVAILABLE | ||
1A | Authentication required | Authentication needed for this transaction. Try again using authentication | AUTHENTICATION_FAILED | Visa only |
1Z | Temporary system error | PROCESSOR_ERROR | ||
9G | Blocked by cardholder/contact cardholder | The cardholder blocked this card. Ask the cardholder to use another payment method | PROCESSOR_ERROR | Visa only |
5C | Transaction not supported/blocked by issuer | The transaction was refused by the card issuer. The shopper can contact their bank or try with a different payment method. | PROCESSOR_ERROR | Visa only |
B1 | Surcharge amount not permitted on Visa cards or EBT food stamps (U.S. acquirers only) | DECLINED_BY_PROCESSOR | ||
B2 | Surcharge amount not supported by debit network issuer | DECLINED_BY_PROCESSOR | ||
N0 | Force STIP | PROCESSOR_ERROR | ||
N3 | Issuer not available | DECLINED_BY_ISSUER | ||
N4 | Limit exceeded | INSUFFICIENT_BALANCE | ||
N5 | Ineligible for resubmission | PROCESSOR_ERROR | ||
N7 | Invalid CVN | INVALID_CVV | ||
N8 | Preauthorized amount exceeded | DECLINED_BY_PROCESSOR | ||
P6 | Denied PIN | CARD_DECLINED | ||
Q1 | Authentication failed | PROCESSOR_ERROR | ||
R0 | Stop payment order | DECLINED_BY_ISSUER | ||
R1 | Revocation of authorization order | TRANSACTION_BLOCKED | ||
R2 | Transaction does not qualify for Visa PIN | DECLINED_BY_ISSUER | ||
R3 | Revocation of authorization order | DECLINED_BY_ISSUER | ||
Z3 | Not available for online transaction | DECLINED_BY_ISSUER |