Skip to main content

​
What are advised actions and advice codes?

When you create a payment via Primer, the request is sent to your chosen processor based on your payment workflows. If the payment is not successful, some processors surface the advice code from the underlying payment method or card networks (e.g. Mastercard’s Merchant Advice Code), enabling you to identify the best course of action for this transaction. Where possible, Primer exposes this underlying advice code, and maps it to a unified advice action so that you can reason about them in a single way across all your payments.

​
Why are advised actions important?

The advised actions and underlying advice codes can be used to determine:
  • Whether the payment can be safely retried
    Some card networks such as Visa/Mastercard charges additional fees whenever the retry limit is exceeded
  • The best course of action to maximize the chances of recovery
    e.g. Retry now, retry later, or use another payment method

​
Primer’s unified advised action

Whenever possible, Primer exposes the unified advised action through this field:
FieldDescriptionPayment Object fields
Primer advised actionIndicates how this declined payment should be handledstatusReason.advisedAction
transactions[x].processorStatusReason.advisedAction
Here are all the valid values for the unified advised action:
Primer advised actionDescriptionExample
RETRY_LATERThe payment was likely declined due to a temporary issue (e.g. Insufficient funds).
The payment can be retried immediately or at a later date.		Recurring payment declined due to insufficient funds
Retry the payment later.
UPDATE_DATAThe payment was likely declined because critical data was missing or out-of-date.
Please ensure you use the most up-to-date payment information and customer details before retrying the payment.		Recurring payment declined due to an expired card
Use Network Tokens to have the latest card, or ask the customer to save a new payment method.
DO_NOT_RETRYThe payment was declined and should not be retried. You can still charge this payment method for future orders or installments.The transaction is not permitted by the issuer
Do not retry this payment. The customer should contact their bank to understand the restriction.
STOP_ALL_PAYMENTSThe processor or payment method explicitly informs you to stop making any payment requests with this payment method.
Please use another payment method to charge this customer.		The customer blocked all payments initiated by you
Do not charge this card again. Ask the customer to save a new payment method.
These fields are returned in the output of the Payments App in Workflows, as well as the API response and the payment status webhook. For example:
JSON
{
    "id": "oWSlcuulG",
    "date": "2023-11-01T13:04:15.704780",
    "status": "DECLINED",
		...
    "statusReason": {
        "type": "ISSUER_DECLINED",
        "declineType": "SOFT_DECLINE",
        "code": "ISSUER_TEMPORARILY_UNAVAILABLE",
        "message": "Processor Network Unavailable - Try Again",

        "advisedAction": "RETRY_LATER"
    },
    "transactions": [
        {
            "date": "2023-10-25T12:23:20.568943",
						...
            "processorStatus": "DECLINED",
            "processorStatusReason": {
                "type": "ISSUER_DECLINED",
                "declineType": "SOFT_DECLINE",
                "code": "ISSUER_TEMPORARILY_UNAVAILABLE",
                "message": "Processor Network Unavailable - Try Again",

                "advisedAction": "RETRY_LATER"
            }
        }
    ]
}

​
Payment method advice code

Where possible, Primer also exposes the advice code and message from the payment method or card network. These are unified across all processors to facilitate analysis on all your payments.
FieldDescriptionPayment Object fields
Payment method advice codeThe raw advice code from the payment method or card network (e.g. Mastercard MAC), unified across all processorsstatusReason.paymentMethodAdviceCode
transactions[x].processorStatusReason.paymentMethodAdviceCode
Payment method advice messageHuman-readable version of the advice code, unified across all processorsstatusReason.paymentMethodAdviceMessage
transactions[x].processorStatusReason.paymentMethodAdviceMessage
These fields are returned in the output of the Payments App in Workflows, as well as the API response and the payment status webhook. For example:
JSON
{
    "id": "oWSlcuulG",
    "date": "2023-11-01T13:04:15.704780",
    "status": "DECLINED",
		...
    "statusReason": {
        "type": "ISSUER_DECLINED",
        "declineType": "SOFT_DECLINE",
        "code": "ISSUER_TEMPORARILY_UNAVAILABLE",
        "message": "Processor Network Unavailable - Try Again",

        "paymentMethodAdviceCode": "24", // MAC 24
        "paymentMethodAdviceMessage: "
        "advisedAction": "RETRY_LATER",
    },
    "transactions": [
        {
            "date": "2023-10-25T12:23:20.568943",
						...
            "processorStatus": "DECLINED",
            "processorStatusReason": {
                "type": "ISSUER_DECLINED",
                "declineType": "SOFT_DECLINE",
                "code": "ISSUER_TEMPORARILY_UNAVAILABLE",
                "message": "Processor Network Unavailable - Try Again",

                "advisedAction": "RETRY_LATER"
            }
        }
    ]
}

​
Supported card networks and processors

The unified advised action and raw advice code are available for the following card networks: And for the following processors:
  • Stripe
  • Braintree
  • Adyen
Please reach out to us directly via our Service Desk if you need support for additional card networks, payment methods, or processors.

​
Card network advice codes

​
Mastercard Merchant Advice Code (MAC)

Merchant Advice Codes (MACs) were introduced by Mastercard to recommend the best course of action to take for each declined payment. Here is the list of MACs, with how they map to Primer’s advised action:
Merchant Advice Code (MAC)MessagePrimer advised action
01Updated information neededUPDATE_DATA
02Cannot be approved now, try again laterRETRY_LATER
03Do not try againDO_NOT_RETRY
04Token requirements not fulfilled for this token typeUPDATE_DATA
21Stop recurring payment requestsSTOP_ALL_PAYMENTS
22Merchant does not qualify for product codeDO_NOT_RETRY
24Retry after 1 hourRETRY_LATER
25Retry after 24 hoursRETRY_LATER
26Retry after 2 daysRETRY_LATER
27Retry after 4 daysRETRY_LATER
28Retry after 6 daysRETRY_LATER
29Retry after 8 daysRETRY_LATER
30Retry after 10 daysRETRY_LATER
40Non-reloadable prepaid cardRETRY_LATER
41Single-use virtual card numberRETRY_LATER
42Sanction score exceeds applicable threshold valueRETRY_LATER
43Multi-use virtual cardRETRY_LATER
Mastercard charges Transaction Processing Excellence (TPA) fees:
  • If the number of authorization attempts on a single card exceed 10 in 24 hours and 35 in 30 days
  • Whenever a merchant retries a payment declined with the MAC 03: Do not try again or 21: Stop recurring payment requests within a 30-day period

​
Visa decline category codes

Unlike Mastercard and their MAC, Visa does not expose a dedicated advice code. Instead, Visa categorizes their decline code into four categories, each with their overarching advice. Primer exposes the category code ("1" to "4") as the advice code.
Category codeMessagePrimer Advised Action
1Issuer will never approveDO_NOT_RETRY or STOP_ALL_PAYMENTS
2Issuer cannot approve at this timeRETRY_LATER
3Issuer cannot approve with these detailsUPDATE_DATA
4Generic responseRETRY_LATER

​
Category 1 - Issuer will never approve

The issuer declined the payment and will never approve a retry. This happens, for instance, when the card number is invalid, or the account is closed.
You are not allowed to retry the payment:
  • Visa charges Excessive Retry Fees for each retry.
  • Visa charges an additional Stop Payment Service (SPS) fee of €1 per retry after receiving a revocation of authorization (R0, R1, or R3).
Raw decline codeRaw decline messagePrimer Advised Action
04Pickup card (no fraud)DO_NOT_RETRY
07Pickup card, special condition (fraud account)DO_NOT_RETRY
12Invalid transactionDO_NOT_RETRY
14Invalid account number (no such number)DO_NOT_RETRY
15No such issuerDO_NOT_RETRY
41Lost card, pick up (fraud account)DO_NOT_RETRY
43Stolen card, pick up (fraud account)DO_NOT_RETRY
44Lost/stolen cardDO_NOT_RETRY
46Closed accountDO_NOT_RETRY
57Transaction not permitted to issuer/cardholderDO_NOT_RETRY
R0Stop payment orderSTOP_ALL_PAYMENTS
R1Revocation of authorization orderSTOP_ALL_PAYMENTS
R3Revocation of all authorizations orderSTOP_ALL_PAYMENTS

​
Category 2 - Issuer cannot approve at this time

The issuer declined the payment but may approve it at a later date. This happens, for instance, when the card has insufficient funds or is temporarily restricted.
You can retry the payment up to 15 times in a 30-day window:
  • Once the limit is exceeded, Visa charges Excessive Retry Fees for each subsequent attempt.
Raw decline codeRaw decline messagePrimer advised action
03Invalid merchantRETRY_LATER
19Re-enter transactionRETRY_LATER
51Insufficient funds / Over credit limitRETRY_LATER
59Suspected fraudRETRY_LATER
60Exceeds approval amount limitRETRY_LATER
61Exceeds approval amount limitRETRY_LATER
62Restricted card (card invalid in region or country)RETRY_LATER
65Exceeds withdrawal frequency limitRETRY_LATER
75Allowable number of PIN entry tries exceededRETRY_LATER
78“Blocked, first used” - Transaction from new cardholder, and card not properly unblockedRETRY_LATER
86Cannot verify PINRETRY_LATER
91Issuer unavailable or switch inoperativeRETRY_LATER
93Transaction cannot be completed; violation of lawRETRY_LATER
N3Cash service not availableRETRY_LATER
N4Cash request exceeds issuer limitRETRY_LATER
9GBlocked by cardholder/contact cardholderRETRY_LATER

​
Category 3 - Issuer cannot approve with these details

The issuer declined the payment because the card details were missing or out-of-date. This happens, for instance, when the card’s CVV or expiry date is missing.
You can retry the payment up to 15 times in a 30-day window:
  • Once the limit is exceeded, Visa charges Excessive Retry Fees for each subsequent attempt.
  • Visa also charges Data Quality Fee if the number of attempts exceed 25,000 transactions.
Raw decline codeRaw decline messagePrimer advised action
54Expired card or expiration date is missingUPDATE_DATA
55Incorrect PIN or PIN missingUPDATE_DATA
70PIN data requiredUPDATE_DATA
82Negative Online CAM, dCVV, iCVV, or CVV resultsUPDATE_DATA
N7Decline for CVV2 failureUPDATE_DATA
1AAdditional customer authentication required (Europe only)UPDATE_DATA

​
Category 4 - Generic response codes

This issuer declined the payment, but the decline reason does not belong to any other category.
You can retry the payment up to 15 times in a 30-day window:
  • Once the limit is exceeded, Visa charges Excessive Retry Fees for each subsequent attempt.
Raw decline codeRaw decline messagePrimer advised action
01Refer to card issuerRETRY_LATER
02Refer to card issuer’s special conditionsRETRY_LATER
05Do not honorRETRY_LATER
06ErrorRETRY_LATER
13Invalid amount or currency conversion field overflowRETRY_LATER
30Format errorRETRY_LATER
31Bank not supported by switchRETRY_LATER
34Suspected fraudRETRY_LATER
36Restricted cardRETRY_LATER
39No credit accountRETRY_LATER
40Requested function not supportedRETRY_LATER
42Invalid accountRETRY_LATER
52No checking accountRETRY_LATER
53No savings accountRETRY_LATER
76Unsolicited reversalRETRY_LATER
81Cryptographic error found in PINRETRY_LATER
89Ineligible to receive financial position information (GIV)RETRY_LATER
92Financial institution or intermediate network facility cannot be found for routingRETRY_LATER
94Request is identified as a duplicateRETRY_LATER
96System malfunctionRETRY_LATER
5CTransaction not supported/blocked by issuerRETRY_LATER
6PVerification data failedRETRY_LATER