Online Payments

Authorization retry logic

Payment authorization declines occur due to temporary issues, data quality problems, or generic response codes. Refer to the following authorization retry logic to determine how to handle declined payment authorizations and when to retry transactions.

Minimize unnecessary re-authorization attempts to avoid additional payment brand transaction fees.
Ensure compliance with payment network rules for retry limits and conditions.
Optimize payment processing for card-not-present transactions.
Determine eligibility for authorization retry based on payment network requirements.

Where to find the retry signals

Retry fields
Card brand	Field to read	Location in response
Mastercard	`merchantAdviceCode`	networkResponse.additionalData.`merchantAdviceCode`
Visa, ChaseNet	`authorizationResponseCategory`	networkResponse.additionalData.`authorizationResponseCategory`

Mastercard

Merchant Advice Codes (MAC) for Mastercard are response codes provided during transaction authorization that indicate when to retry a declined transaction. These codes help you optimize your authorization retry strategy by reducing unnecessary retries, improving approval rates, and minimizing costs for declined transactions.

The following table lists merchantAdviceCode, reasons for decline, and actions for merchants.

Mastercard- merchant advice code
merchantAdviceCode	Reason for decline examples	Suggested merchant action
01–New account information available. Obtain new account information	• Expired card • Account upgrade • Portfolio sale • Conversion	Updated information found to be available in Mastercard ABU database. Secure new information before reattempting
02–Try again later. Recycle transaction in 72 hours	• Over credit limit • Insufficient funds	Retry transaction after 72 hours.
03–Do not try again. Obtain another type of payment from consumer.	• Account closed • Fraudulent	Do not retry. Updated credentials were not found to be available in Mastercard ABU database.
04–Token requirements not fulfilled for this token type. Resubmit with proper cryptography.		Submit again with proper cryptography
21–Do not try again. Issuer has blocked recurring payment transaction	• Cardholder cancelled recurring agreement	Do not retry
24–Retry after 1 hour		Retry after 1 hour
25–Retry after 24 hours		Retry after 24 hours
26–Retry after 2 days		Retry after 2 days
27–Retry after 4 days		Retry after 4 days
28–Retry after 6 days		Retry after 6 days
29-Retry after 8 days		Retry after 8 days
30–Retry after 10 days		Retry after 10 days

Sample Mastercard decline response

Json

{
  "networkResponse": {
    "addressVerificationResult": "ADDRESS_POSTALCODE_MATCH",
    "addressVerificationResultCode": "I3",
    "additionalData": {
      "electronicCommerceIndicator": "2",
      "merchantAdviceCode": "01 - New account information available. Obtain new account information.",
      "posEntryMode": "01"
    },
    "networkResponseCode": "51"
  }
}

Visa and ChaseNet

Visa reauthorization rules are determined by the authorizationResponseCategory returned in a declined authorization. The platform provides authorizationResponseCategory, enabling you to align your logic with Visa’s guidelines for reducing unnecessary reattempts.

The following table maps the Visa authorization response code categories, including their descriptions, and whether a retry is allowed.

Visa authorization response code categories
`authorizationResponseCategory`	Description	Retry allowed
1 – Issuer will never approve	A category of decline response codes that indicates the card is blocked for use or never existed and means there is no circumstance in which the Issuer will grant an approval.	No
2 – Issuer cannot approve at this time	A category of decline response codes that indicates the Issuer may approve, but cannot do so now, perhaps due to temporary condition like lack of funds or account restrictions. Note: Merchants must limit reattempts to a maximum of 15 over 30 days.	Yes - Max 15x in 30 days
3 – Issuer cannot approve with these details	A category of decline response codes that indicates data quality issues are present. Where invalid payment or authentication data has been provided the Issuer may approve if valid information is sent. Note: Merchants must limit reattempts to a maximum of 15 over 30 days.	Yes- Max 15x in 30 days
4 – Generic response codes	This category includes all other decline response codes not included in category 1, 2 and 3. Note: Merchants must limit reattempts to a maximum of 15 over 30 days.	Yes- Max 15x in 30 days
N – Not available	This category is assigned when: - Visa transaction is sent to a non-Visa Payment Brand due to failover - Merchant Services error condition occurs - Category Code is unavailable for return (used as a default value) - Transaction is an Interlink transaction for Orbital BIN 000001 or direct to Stratus merchants	N/A
A – Approved	This category is returned when a transaction is approved, partially approved, or there is no reason for the Issuer to decline.	N/A
X – Not supported MOP	This category is returned for non-Visa transactions.	N/A

Sample Visa decline response

Json

{
    "networkResponse": {
        "addressVerificationResult": "ADDRESS_POSTALCODE_MATCH",
        "addressVerificationResultCode": "I3",
        "additionalData": {
            "electronicCommerceIndicator": "7",
            "authorizationResponseCategory": "4 - Generic response codes"
        },
        "paymentAccountReference": "Q1J4Z28RKA1EBL470G9XYG90R5D3E",
        "networkResponseCode": "05"
    }
}

Key API response fields

The following table describes key API response fields, their purpose, and valid values to help you interpret and handle payment transaction results.

`API response fields`
API Field	Description	Valid Values
`responseStatus`	Indicates whether API request resulted in success, error, or denial.	SUCCESS,DENIED,ERROR
`responseCode`	Short explanation for the response status.
`responseMessage`	Long explanation of the response code.
`transactionState`	The result of the current request, such as a payment or refund. To determine if a transaction was approved or declined, check the responseStatus.	AUTHORIZED,CLOSED,DECLINED,ERROR,PENDING,VOIDED
`hostmessage`	Message received from the issuer, network, or processor.
networkResponse.`networkResponseCode`	Network provided error or reason code.	00
networkResponse.additionalData.`merchantAdviceCode`	Indicates the reason for declining a Mastercard or Visa transaction and actions the merchant can take.	01–New account information available. Obtain new account information. 02–Try again later. Recycle transaction in 72 hours. 03–Do not try again. Obtain another type of payment from consumer. 04–Token requirements not fulfilled for this token type. Resubmit with proper cryptography. 21–Do not try again. Issuer has blocked recurring payment transaction. 22–Merchant does not qualify for product code. Obtain another type of payment from customer. 24–Retry after 1 hour (Mastercard use only) 25–Retry after 24 hours (Mastercard use only) 26–Retry after 2 days (Mastercard use only) 27–Retry after 4 days (Mastercard use only) 28–Retry after 6 days (Mastercard use only) 29-Retry after 8 days (Mastercard use only) 30–Retry after 10 days (Mastercard use only) 40 – Non-reloadable prepaid card (Mastercard use only) 41–Single-use virtual card number (Mastercard use only) 43 - Consumer multi-use virtual card number (Mastercard use only)
additionalData.`authorizationResponseCategory`	The firm's high level grouping of the Payment Network Authorization Response Code to provide a consistent response to the merchant, regardless of the payment network.	1 – Issuer will never approve 2 – Issuer cannot approve at this time 3 – Issuer cannot approve with these details 4 – Generic response codes N – Not available A – Approved X – Not supported MOP