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:

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