ISO 8583 Response Codes

ISO 8583 is the international standard for financial transaction card-originated messages. When a credit or debit card transaction is processed, the card issuer returns a response code that indicates the outcome of the authorization request. Understanding these codes helps you optimize your payment flow and provide better customer experiences.

See how these codes map to EBANX response descriptionschevron_right

Overview

When EBANX processes a card transaction, the issuing bank returns an ISO 8583 response code. EBANX translates these technical codes into user-friendly descriptions in the API response. However, understanding the underlying ISO codes can help you make better decisions about retry logic, customer messaging, and fraud prevention.

Important Considerations

ISO 8583 response codes are broad definitions that may be interpreted differently by card brands, banks, and regions. Authorization systems are built upon each banking institution's understanding of the rules, so the same code may have different meanings depending on the country or issuer. EBANX maintains direct relationships with the main banks in each region, and our status descriptions already take into account the regional understanding of each code. For the most accurate guidance, rely on the EBANX description field in your API responses.

The response codes are returned in the payment.transaction_status object:

{
  "payment": {
    "transaction_status": {
      "acquirer": "EBANX",
      "code": "NOK",
      "description": "Not accepted",
      "iso_code": "51",
      "mac_code": "02"
    }
  }
}

Info

The iso_code and mac_code fields are returned only for declined transactions. If you need these fields in your API responses, contact your EBANX Account Manager to enable them.

Tip

ISO 8583 response codes are available for card transactions processed in Argentina, Brazil, Chile, Colombia, Dominican Republic, Mexico, and Peru.

Mexico

In Mexico, card brand schemes have less control over the local payment industry compared to other regions. As a result, ISO response codes may not be strictly enforced, and some banks may use codes differently than the standard definitions. For Mexican transactions, rely primarily on the EBANX description field for accurate decline reasons.

Understanding the MAC Code

For Mastercard transactions, issuers may return an additional MAC code (Merchant Advice Code) alongside the ISO code. The MAC code provides more granular information about why a transaction was declined and specific guidance on retry behavior.

MAC code availability depends on the processing path. Not all Mastercard transactions will include a MAC code. When a mac_code is present, use it to determine retry logic. When no MAC code is available, use the ISO code guidance from the tables below.

When a mac_code is present, it takes precedence over the iso_code for determining retry logic. The MAC code indicates whether you should request updated card information, retry after a specific delay, or not retry at all.

The mac_code field is only returned for Mastercard transactions when the issuer provides this additional information. For Visa and Elo transactions, only the iso_code is returned.

Response Code Categories

ISO 8583 response codes fall into several categories that determine how you should handle the transaction outcome. The following tables apply to all card brands. For Mastercard transactions, if a mac_code is present in the response, refer to the Mastercard MAC Codes section below for more specific retry guidance.

Approved Transactions

This code indicates successful authorization.

Code	Description	Action
00	Approved	Transaction successful

Hard Declines - Should Not Retry

Hard declines indicate permanent issues that are unlikely to succeed on retry. Retrying these transactions may result in additional fees and can negatively impact your authorization rates.

Note

Elo is a Brazilian card brand. Codes marked with 'Elo' apply exclusively to transactions processed in Brazil.

Code	Description	Brands	Reason
04	Pick up card	Visa, Mastercard	Card may be reported lost or stolen
07	Pick up card, special condition	Visa, Mastercard	Fraud account suspected
12	Invalid transaction	Visa, Mastercard, Elo	Transaction type not supported
13	Invalid amount	Elo	Amount format or value invalid
14	Invalid card number	Visa, Mastercard, Elo	Card number does not exist
15	No such issuer	Visa, Mastercard	Card BIN not recognized
19	Re-enter transaction	Elo	Transaction cannot be processed
23	Unacceptable fee	Elo	Fee structure not accepted
30	Format error	Elo	Message format invalid
41	Lost card	Visa, Mastercard, Elo	Card reported as lost
43	Stolen card	Visa, Mastercard, Elo	Card reported as stolen
46	Closed account	Visa, Mastercard, Elo	Account has been closed
56	No card record	Elo	Card not found in issuer system
57	Transaction not permitted to cardholder	Visa, Mastercard, Elo	Card restrictions apply
58	Transaction not permitted to terminal	Elo	Terminal restrictions apply
64	Original amount incorrect	Elo	Amount mismatch
76	Invalid account	Elo	Account number invalid
77	Invalid account	Elo	Account number invalid
83	Security decline	Elo	Security validation failed
R0	Stop payment order	Visa	Customer requested stop payment
R1	Revocation of authorization	Visa	Authorization has been revoked
R3	Revocation of all authorizations	Visa	All authorizations revoked
FM	Fraud monitoring	Elo	Transaction blocked by fraud systems

Soft Declines - Retry Possible

Soft declines are temporary issues that may succeed if retried. These are typically caused by temporary issuer system issues or transaction limits that may reset. However, be mindful of retry limits to avoid penalties.

Code	Description	Brands	Recommended Action
03	Invalid merchant	Visa, Mastercard	Retry after verifying merchant configuration
04	Pick up card	Elo	Retry after a short delay
05	Do not honor	Visa, Mastercard	Retry after a short delay
06	Error	Visa, Mastercard, Elo	Retry after a short delay
13	Invalid amount	Visa, Mastercard	Retry with corrected amount
19	Re-enter transaction	Visa, Mastercard	Retry the transaction
38	Exceeded PIN tries	Elo	Advise customer to wait before retrying
39	No credit account	Visa, Mastercard	Retry with different payment method
51	Insufficient funds	Visa, Mastercard, Elo	Advise customer to use a different card or try again later
52	No checking account	Visa, Mastercard	Retry with different account type
53	No savings account	Visa, Mastercard	Retry with different account type
58	Transaction not permitted	Visa, Mastercard	Retry after verifying terminal configuration
59	Suspected fraud	Visa, Mastercard, Elo	Review transaction and retry if legitimate
61	Exceeds withdrawal limit	Visa, Mastercard, Elo	Retry with a lower amount or advise customer to try again later
62	Restricted card	Visa, Mastercard, Elo	Retry may succeed. Card has geographic or merchant restrictions
64	Original amount incorrect	Visa, Mastercard	Retry with corrected amount
65	Exceeds withdrawal frequency	Visa, Mastercard, Elo	Advise customer to try again later
74	PIN error	Visa, Mastercard	Advise customer to verify PIN
75	PIN tries exceeded	Visa, Mastercard, Elo	Advise customer to wait before retrying
76	Invalid account	Visa, Mastercard	Retry with corrected account information
78	Card not activated	Visa, Mastercard, Elo	Advise customer to activate their card first
81	Cryptographic error	Visa, Mastercard	Retry the transaction
86	Cannot verify PIN	Visa, Mastercard	Retry the transaction
91	Issuer or switch inoperative	Visa, Mastercard, Elo	Retry after a short delay
92	Routing error	Visa, Mastercard	Retry after a short delay
93	Violation of law	Visa, Mastercard	Review transaction and retry if compliant
94	Duplicate transmission	Visa, Mastercard	Verify transaction status before retrying
96	System malfunction	Visa, Mastercard	Retry after a short delay
N0	Force STIP	Visa	Retry the transaction
N3	Cash service not available	Visa	Retry the transaction
N4	Cash request exceeds issuer limit	Visa	Retry with a lower amount
5C	Card not on file	Visa	Verify card enrollment status
9G	Contact card issuer	Visa	Advise customer to contact their bank

Data Quality Issues

These codes indicate problems with the transaction data that require customer correction before retrying.

Code	Description	Brands	Recommended Action
54	Expired card	Visa, Mastercard, Elo	Advise customer to use a different card or update expiration date
55	Incorrect PIN	Visa, Mastercard, Elo	Advise customer to verify PIN
63	Security violation	Elo	Advise customer to verify card security features
70	PIN data required	Visa, Mastercard	Advise customer that PIN entry is required
82	CVV mismatch	Visa, Mastercard, Elo	Advise customer to verify security code
1A	Additional customer authentication required	Visa	Redirect customer to complete additional verification
6P	PIN required	Visa	Transaction requires PIN entry
N7	CVV mismatch	Visa	Advise customer to verify security code

Brand-Specific Codes

Some response codes are specific to certain card brands. Understanding these can help you provide more accurate customer messaging.

Visa-Specific Codes

Code	Description	Category	Recommended Action
1A	Additional customer authentication required	Data Quality	Redirect to 3D Secure or additional verification
5C	Card not on file	Soft Decline	Verify card enrollment status
6P	PIN required	Data Quality	Transaction requires PIN entry
9G	Contact card issuer	Soft Decline	Advise customer to contact their bank
B1	Surcharge not permitted	Generic	Remove surcharge from transaction
B2	Surcharge not supported	Generic	Remove surcharge from transaction
N0	Force STIP	Generic	Retry the transaction
N7	CVV mismatch	Data Quality	Advise customer to verify security code
N8	Cryptographic failure	Generic	Retry the transaction
R2	Issuer system unavailable	Generic	Retry after a short delay
Z5	Fallback not allowed	Generic	Use chip or contactless instead of magnetic stripe

Mastercard MAC Codes

For Mastercard transactions, the mac_code field provides specific retry guidance. When present, the MAC code determines the recommended action regardless of the ISO code. When no MAC code is available, use the ISO code guidance from the tables above.

MAC Code	Description	Category	Recommended Action
01	Updated information required	Soft Decline	Request updated card information from customer
02	Try again later	Soft Decline	Retry after a short delay
03	Account closed or fraudulent	Hard Decline	Do not retry
04	Issuer cannot approve now	Soft Decline	Retry after a short delay
21	Cancelled cardholder agreement	Hard Decline	Do not retry
24	Retry in 1 hour	Timed Retry	Retry after 1 hour
25	Retry in 24 hours	Timed Retry	Retry after 24 hours
26	Retry in 2 days	Timed Retry	Retry after 2 days
27	Retry in 4 days	Timed Retry	Retry after 4 days
28	Retry in 6 days	Timed Retry	Retry after 6 days
29	Retry in 8 days	Timed Retry	Retry after 8 days
30	Retry in 10 days	Timed Retry	Retry after 10 days
40	Consumer non-reloadable prepaid card	Informational	May appear in approved or declined transactions
41	Consumer single-use virtual card number	Informational	May appear in approved or declined transactions

Note

When processing Mastercard transactions, always check for the presence of a mac_code. If present, use the MAC code guidance for retry decisions rather than the ISO code alone. If no MAC code is available, use the ISO code guidance from the tables above. Note that MAC codes 40 and 41 are informational and may appear even in approved transactions.

Elo-Specific Codes (Brazil Only)

Elo is a Brazilian card brand, so these codes apply exclusively to transactions processed in Brazil.

Code	Description	Category	Reason
FM	Fraud monitoring	Hard Decline	Should not retry. Transaction blocked by Elo fraud systems

Retry Limits by Brand

Card brands enforce limits on how many times you can retry a declined transaction. Exceeding these limits may result in penalties. EBANX enforces the following retry thresholds:

Brand	Maximum Retry Attempts	Time Window
Visa	20 attempts	30 rolling days
Mastercard	7 attempts (24h) / 35 attempts (total)	24 hours / 30 rolling days
Elo (Brazil only)	15 attempts	Calendar month

After reaching these limits for soft declines, further retry attempts will be blocked until the time window resets.

Best Practices for Handling Response Codes

When implementing your payment flow, consider these best practices for handling ISO 8583 response codes.

Implement smart retry logic. Not all declines should be retried. Retrying hard declines wastes resources and can negatively impact your authorization rates. Focus retry attempts on soft declines and respect the retry limits per brand.

Check for MAC codes on Mastercard transactions. When a mac_code is present, use it to determine retry behavior. MAC codes provide more specific guidance than ISO codes alone, including exact retry timing for timed retry codes. When no MAC code is available, use the ISO code guidance.

Provide clear customer messaging. Translate technical decline reasons into actionable customer messages. Instead of showing "Code 51", display "Your card has insufficient funds. Please try a different payment method."

Monitor decline patterns. Track your decline rates by response code to identify issues. A sudden increase in specific codes may indicate fraud attacks, integration issues, or changes in issuer policies.

Use 3D Secure for authentication-related declines. If you see frequent 1A (additional authentication required) codes, consider implementing 3D Secure 2.0 to reduce these declines.

Contact EBANX support for persistent issues. If you experience high decline rates or unusual response codes, our support team can help investigate and optimize your integration.

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.