Advised actions

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:

Field	Description	Payment Object fields
Primer advised action	Indicates how this declined payment should be handled	`statusReason.advisedAction` `transactions[x].processorStatusReason.advisedAction`

Here are all the valid values for the unified advised action:

Primer advised action	Description	Example
`RETRY_LATER`	The 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_DATA`	The 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_RETRY`	The 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_PAYMENTS`	The 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.

Field	Description	Payment Object fields
Payment method advice code	The raw advice code from the payment method or card network (e.g. Mastercard MAC), unified across all processors	`statusReason.paymentMethodAdviceCode` `transactions[x].processorStatusReason.paymentMethodAdviceCode`
Payment method advice message	Human-readable version of the advice code, unified across all processors	`statusReason.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:

Mastercard - using the Merchant Advice Code (MAC)
Visa - using the Visa decline category code

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)	Message	Primer advised action
01	Updated information needed	`UPDATE_DATA`
02	Cannot be approved now, try again later	`RETRY_LATER`
03	Do not try again	`DO_NOT_RETRY`
04	Token requirements not fulfilled for this token type	`UPDATE_DATA`
21	Stop recurring payment requests	`STOP_ALL_PAYMENTS`
22	Merchant does not qualify for product code	`DO_NOT_RETRY`
24	Retry after 1 hour	`RETRY_LATER`
25	Retry after 24 hours	`RETRY_LATER`
26	Retry after 2 days	`RETRY_LATER`
27	Retry after 4 days	`RETRY_LATER`
28	Retry after 6 days	`RETRY_LATER`
29	Retry after 8 days	`RETRY_LATER`
30	Retry after 10 days	`RETRY_LATER`
40	Non-reloadable prepaid card	`RETRY_LATER`
41	Single-use virtual card number	`RETRY_LATER`
42	Sanction score exceeds applicable threshold value	`RETRY_LATER`
43	Multi-use virtual card	`RETRY_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 code	Message	Primer Advised Action
1	Issuer will never approve	`DO_NOT_RETRY` or `STOP_ALL_PAYMENTS`
2	Issuer cannot approve at this time	`RETRY_LATER`
3	Issuer cannot approve with these details	`UPDATE_DATA`
4	Generic response	`RETRY_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 code	Raw decline message	Primer Advised Action
04	Pickup card (no fraud)	`DO_NOT_RETRY`
07	Pickup card, special condition (fraud account)	`DO_NOT_RETRY`
12	Invalid transaction	`DO_NOT_RETRY`
14	Invalid account number (no such number)	`DO_NOT_RETRY`
15	No such issuer	`DO_NOT_RETRY`
41	Lost card, pick up (fraud account)	`DO_NOT_RETRY`
43	Stolen card, pick up (fraud account)	`DO_NOT_RETRY`
44	Lost/stolen card	`DO_NOT_RETRY`
46	Closed account	`DO_NOT_RETRY`
57	Transaction not permitted to issuer/cardholder	`DO_NOT_RETRY`
R0	Stop payment order	`STOP_ALL_PAYMENTS`
R1	Revocation of authorization order	`STOP_ALL_PAYMENTS`
R3	Revocation of all authorizations order	`STOP_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 code	Raw decline message	Primer advised action
03	Invalid merchant	`RETRY_LATER`
19	Re-enter transaction	`RETRY_LATER`
51	Insufficient funds / Over credit limit	`RETRY_LATER`
59	Suspected fraud	`RETRY_LATER`
60	Exceeds approval amount limit	`RETRY_LATER`
61	Exceeds approval amount limit	`RETRY_LATER`
62	Restricted card (card invalid in region or country)	`RETRY_LATER`
65	Exceeds withdrawal frequency limit	`RETRY_LATER`
75	Allowable number of PIN entry tries exceeded	`RETRY_LATER`
78	“Blocked, first used” - Transaction from new cardholder, and card not properly unblocked	`RETRY_LATER`
86	Cannot verify PIN	`RETRY_LATER`
91	Issuer unavailable or switch inoperative	`RETRY_LATER`
93	Transaction cannot be completed; violation of law	`RETRY_LATER`
N3	Cash service not available	`RETRY_LATER`
N4	Cash request exceeds issuer limit	`RETRY_LATER`
9G	Blocked by cardholder/contact cardholder	`RETRY_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 code	Raw decline message	Primer advised action
54	Expired card or expiration date is missing	`UPDATE_DATA`
55	Incorrect PIN or PIN missing	`UPDATE_DATA`
70	PIN data required	`UPDATE_DATA`
82	Negative Online CAM, dCVV, iCVV, or CVV results	`UPDATE_DATA`
N7	Decline for CVV2 failure	`UPDATE_DATA`
1A	Additional 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 code	Raw decline message	Primer advised action
01	Refer to card issuer	`RETRY_LATER`
02	Refer to card issuer’s special conditions	`RETRY_LATER`
05	Do not honor	`RETRY_LATER`
06	Error	`RETRY_LATER`
13	Invalid amount or currency conversion field overflow	`RETRY_LATER`
30	Format error	`RETRY_LATER`
31	Bank not supported by switch	`RETRY_LATER`
34	Suspected fraud	`RETRY_LATER`
36	Restricted card	`RETRY_LATER`
39	No credit account	`RETRY_LATER`
40	Requested function not supported	`RETRY_LATER`
42	Invalid account	`RETRY_LATER`
52	No checking account	`RETRY_LATER`
53	No savings account	`RETRY_LATER`
76	Unsolicited reversal	`RETRY_LATER`
81	Cryptographic error found in PIN	`RETRY_LATER`
89	Ineligible to receive financial position information (GIV)	`RETRY_LATER`
92	Financial institution or intermediate network facility cannot be found for routing	`RETRY_LATER`
94	Request is identified as a duplicate	`RETRY_LATER`
96	System malfunction	`RETRY_LATER`
5C	Transaction not supported/blocked by issuer	`RETRY_LATER`
6P	Verification data failed	`RETRY_LATER`

​What are advised actions and advice codes?

​Why are advised actions important?

​Primer’s unified advised action

​Payment method advice code

​Supported card networks and processors

​Card network advice codes

​Mastercard Merchant Advice Code (MAC)

​Visa decline category codes

​Category 1 - Issuer will never approve

​Category 2 - Issuer cannot approve at this time

​Category 3 - Issuer cannot approve with these details

​Category 4 - Generic response codes

What are advised actions and advice codes?

Why are advised actions important?

Primer’s unified advised action

Payment method advice code

Supported card networks and processors

Card network advice codes

Mastercard Merchant Advice Code (MAC)

Visa decline category codes

Category 1 - Issuer will never approve

Category 2 - Issuer cannot approve at this time

Category 3 - Issuer cannot approve with these details

Category 4 - Generic response codes