Retry Advice

Overview

When a card payment is declined, the issuing bank and card scheme return guidance on whether the transaction can be retried, and if so, when. Acquired.com interprets this guidance and returns it as a retry_advice object in the API response — giving you a clear, actionable recommendation without needing to interpret raw scheme-specific codes yourself.

Retry Advice is particularly valuable for recurring and merchant-initiated payments, where an automated retry strategy can significantly improve approval rates and reduce involuntary churn.

📘

Note

Retry Advice is returned via the API only. For Hosted Checkout and Components integrations, use GET /transactions/{transaction_id} to retrieve advice after the transaction completes.

How it works

When a transaction is processed, Acquired.com receives a response from the acquiring bank that may include a Merchant Advice Code (MAC) from Mastercard or an issuer response code that maps to a Visa decline category. Acquired.com translates these signals into a canonical, acquirer-agnostic retry_advice object so that your integration receives consistent guidance regardless of which acquirer processes the transaction.

The advice is informational only. Acquired.com does not automatically retry transactions or enforce stop-processing rules based on advice values. You are responsible for implementing your own retry logic using the guidance provided.

The retry_advice object

When advice is available for a transaction, the response includes a retry_advice object positioned after the check object:

{
  "transaction_id": "a7e3fde5-5b3-44f4-9915-782bc71243717",
  "status": "declined",
  "reason": "insufficient_funds",
  "issuer_response_code": "51",
  "check": {
    "avs_line1": "matched",
    "avs_postcode": "matched",
    "cvv": "matched"
  },
  "retry_advice": {
    "category": "retry_later",
    "detail": null,
    "retry_after": "2026-03-15T00:00:00Z",
    "acquirer_code": "25"
  },
  "bin": {
    "issuing_bank": "MONZO BANK LIMITED",
    "card_category": "DEBIT",
    "product_type": "CONSUMER",
    "card_level": "BLANK",
    "issuing_country": "UNITED KINGDOM",
    "issuing_country_iso2": "GB",
    "eea_indicator": true,
    "non_reloadable": false
  },
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/a7e3fde5-5b83-44f4-9915-782bc7341717"
    }
  ]
}

When no advice is available for a transaction, retry_advice is returned as null. The field is always present in the response and is never omitted.

Field reference

Advice categories

The category field tells you what action to take. Below are all possible values:

Card product limitations

When category is card_product_limitations, the detail field provides specifics about the card type:

Understanding retry_after

When advice includes retry timing guidance, the retry_after field contains an RFC 3339 UTC timestamp representing the earliest recommended retry time.

How retry_after is calculated:

• Hour-based guidance (e.g. "retry after 1 hour"): retry_after is set to the current time plus the specified duration.
• Day-based guidance (e.g. "retry after 2 days"): retry_after is set to 00:00:00Z on the recommended retry day (i.e. midnight UTC, today + N days).

Important considerations:

• retry_after is a recommended earliest retry time. It is not an optimal retry window or a guaranteed approval time.
• The timestamp does not account for weekends, bank holidays, merchant operating hours, or customer context.
• You should apply your own optimisation logic (e.g. retry during peak approval hours for your customer base) when determining the actual retry time.
• retry_after will never be set to a time in the past.
• For Visa transactions, retry_after is always null because Visa does not provide retry timing guidance.

How Visa and Mastercard differ

Acquired.com abstracts the differences between Visa and Mastercard into a single retry_advice model, but it's helpful to understand how the underlying guidance differs.

Mastercard

Mastercard returns explicit Merchant Advice Codes (MAC) in the authorisation response. These codes provide granular guidance including specific retry timing windows (e.g. retry after 1 hour, after 24 hours, after 2 days, up to 10 days). Acquired.com maps these directly to canonical categories with retry_after timestamps.

Some Mastercard advice codes (notably those related to lifecycle and security declines) require additional context from the issuer response to interpret correctly. In these cases, Acquired.com uses Mastercard's Authorization Optimizer signals to determine the appropriate advice category.

Visa

Visa does not include retry advice in authorisation responses. Instead, Visa classifies issuer response codes into four decline categories:

Acquired.com derives Visa advice internally by mapping issuer response codes to the appropriate category. Because Visa does not provide retry timing, retry_after and acquirer_code are always null for Visa transactions.

Supported endpoints

The retry_advice object is returned on the following API endpoints:

📘

Note

retry_advice is not returned in Hosted Checkout, Components, or Payment Links responses. For these integration methods, retrieve advice by calling GET /transactions/{transaction_id} after the transaction completes.

Response examples

Declined with retry timing (Mastercard)

The issuer has declined due to insufficient funds and the scheme recommends retrying after 24 hours:

{
  "transaction_id": "a7e3fde5-5b83-44f4-9915-782bc7121717",
  "status": "declined",
  "reason": "insufficient_funds",
  "issuer_response_code": "51",
  "check": {
    "avs_line1": "matched",
    "avs_postcode": "matched",
    "cvv": "matched"
  },
  "retry_advice": {
    "category": "retry_later",
    "detail": null,
    "retry_after": "2026-03-11T00:00:00Z",
    "acquirer_code": "25"
  },
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/a7e3fde5-5b83-44f4-9915-782bc7121717"
    }
  ]
}

Do not retry (Mastercard)

The issuer has permanently declined. The card account is closed or fraudulent. Do not attempt this transaction again:

{
  "transaction_id": "c3f8a219-6e42-4d8b-b1a7-9f2e1c5d3a67",
  "status": "declined",
  "reason": "do_not_honour",
  "issuer_response_code": "05",
  "check": {
    "avs_line1": "not_matched",
    "avs_postcode": "not_matched",
    "cvv": "not_matched"
  },
  "retry_advice": {
    "category": "do_not_retry",
    "detail": null,
    "retry_after": null,
    "acquirer_code": "03"
  },
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/c3f8a219-6e42-4d8b-b1a7-9f2e1c5d3a67"
    }
  ]
}

Card product limitation (prepaid card)

The card is a non-reloadable prepaid card and is not suitable for recurring billing:

{
  "transaction_id": "91b4e7d3-2a5f-4c18-96e0-d7f3b8a12c45",
  "status": "declined",
  "reason": "generic_decline",
  "issuer_response_code": "05",
  "check": {
    "avs_line1": "matched",
    "avs_postcode": "matched",
    "cvv": "matched"
  },
  "retry_advice": {
    "category": "card_product_limitations",
    "detail": "non_reloadable_prepaid",
    "retry_after": null,
    "acquirer_code": "40"
  },
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/91b4e7d3-2a5f-4c18-96e0-d7f3b8a12c45"
    }
  ]
}

Visa decline — data quality issue

Visa has indicated the decline is due to invalid transaction data. Correct the data and retry:

{
  "transaction_id": "58d1f4a6-7b3e-49c2-a5d8-e6f2c9b01d83",
  "status": "declined",
  "reason": "invalid_card_number",
  "issuer_response_code": "54",
  "check": {
    "avs_line1": "not_checked",
    "avs_postcode": "not_checked",
    "cvv": "not_checked"
  },
  "retry_advice": {
    "category": "update_details",
    "detail": null,
    "retry_after": null,
    "acquirer_code": null
  },
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/58d1f4a6-7b3e-49c2-a5d8-e6f2c9b01d83"
    }
  ]
}

No advice available

When no Merchant Advice Code is returned by the acquirer or the issuer response code does not map to a known category, retry_advice is null:

{
  "transaction_id": "d4a72f19-8c6e-4b35-a1e9-3f5d7c82b460",
  "status": "declined",
  "reason": "generic_decline",
  "issuer_response_code": "05",
  "check": {
    "avs_line1": "matched",
    "avs_postcode": "matched",
    "cvv": "matched"
  },
  "retry_advice": null,
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/d4a72f19-8c6e-4b35-a1e9-3f5d7c82b460"
    }
  ]
}

Building your retry logic

Retry Advice provides the signals — your system needs to act on them. Here's a recommended approach for handling the retry_advice object:

Decision flow

1. Check if retry_advice is present. If null, apply your default retry logic.

2. Read the category value and route to the appropriate handler:

   • do_not_retry, cancelled, scheme_blocked → Stop. Remove the payment method from your retry queue. Notify the customer to update their payment details.

   • retry_later → Schedule a retry. If retry_after is present, schedule no earlier than that timestamp. If retry_after is null, wait at least 1 hour.

   • update_credentials → Request updated card details. Trigger Account Updater if available, or prompt the cardholder via email or in-app notification.

   • update_details → Fix the request data. Check for expired card details, incorrect CVV, or other data quality issues before retrying.

   • customer_action_required → Notify the customer. The cardholder needs to contact their bank directly. Do not retry automatically.

   • card_product_limitations → Check the detail field. If the card is prepaid or single-use, prompt the customer to provide a different payment method.

   • unknown → Treat with caution. You may retry, but apply conservative limits and monitor outcomes.

3. Always respect scheme retry limits. Regardless of the advice received, card schemes enforce maximum retry limits:

   • Mastercard: 10 retries per card per merchant in 24 hours; 35 retries in 30 days.
   • Visa: 15 retries in 30 days for Category 2 and 3 declines; zero retries for Category 1 (do not retry).

Scheme compliance and fees

Card schemes enforce rules around transaction retries. Failing to follow retry advice can result in fees.

Mastercard — Transaction Processing Excellence (TPE)

Mastercard's TPE programme monitors retry behaviour and charges fees for excessive or non-compliant retries:

• Excessive retry fee: Retrying a transaction more than 35 times in 30 days on the same card/merchant combination incurs a fee per additional attempt.
• Do-not-retry violations: Submitting a card-not-present authorisation on a card that was declined with do_not_retry or cancelled advice within the previous 30 days incurs a per-transaction fee — even if the transaction amount differs.
• Authorization Optimizer fee: A fee applies when specific combinations of issuer response codes and Merchant Advice Codes are used.

Visa — Excessive reattempt rules

Visa classifies decline response codes into categories and enforces reattempt limits:

• Category 1 (do not retry): Any reattempt after a Category 1 decline incurs a fee.
• Category 2 and 3: Up to 15 reattempts are permitted within a 30-day rolling window. Each attempt beyond 15 incurs a fee.

How Retry Advice helps

By following the category and retry_after guidance in the retry_advice object, you can:

• Avoid retrying permanently declined transactions (do_not_retry, cancelled)
• Space retries appropriately using retry_after timestamps
• Reduce scheme fees by staying within permitted retry limits
• Improve approval rates by retrying at the recommended time

📘

Note

For more information on Visa's monitoring programmes, see our VAMP Frequently Asked Questions guide.

Availability

Integration methods

Acquirer support

Retry Advice coverage depends on the acquiring bank processing the transaction:

Frequently asked questions

Does Acquired.com automatically retry declined transactions based on advice?

No. Retry Advice is informational only. Acquired.com returns the advice in the API response and it is your responsibility to implement retry logic.

Will retry_advice always be present on declined transactions?

The retry_advice field is always present in the API response, but its value may be null if the acquirer did not return a Merchant Advice Code or the issuer response code does not map to a known category.

What should I do if category is unknown?

This means the advice code could not be fully interpreted. You may apply your default retry logic, but should monitor the acquirer_code value for patterns. As Acquired.com expands its mapping coverage, some unknown values will be reclassified to more specific categories in future releases.

Can I use retry_advice for one-off card payments, or is it only for recurring?

Retry Advice is returned on all card transaction types — one-off, recurring, and merchant-initiated. While it is most valuable for recurring payments (where automated retry logic is common), the guidance is equally applicable to any declined transaction.