> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/payment-services/network-tokenization) 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 JSON theme={"dark"}
{
"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 JSON theme={"dark"}
{
"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)](#mastercard-merchant-advice-code-mac)
* **Visa** - using the [Visa decline category code](#visa-decline-category-codes)
And for the following processors:
* Stripe
* Braintree
* Adyen
Please reach out to us directly via our [Service Desk](https://primerapi.atlassian.net/servicedesk/customer/portal/11) 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` |