MasterCard Decline Reason Code Service
Best practices and reccommendations for dealing with MasterCard declines
MasterCard introduced a new Decline Reason Code Service for Card Not Present (CNP) payments in 2021. This was renamed to the MasterCard Authorisation Optimiser in August 2022.
The Service provides enhanced information about transaction declines while mandating some changes to Issuer usage of the standard [05 – Do Not Honor] responses. Moto and Card Present (CP) payments are out of scope.
It is important for merchants to assess these changes, particularly with respect to guidance regarding retries, and to also know exactly how to receive the enhanced data in responses from PXP Financial.
Merchant Benefits
The new service will provide more meaningful decline information to merchants and also provide guidance to optimise authorisation retry strategies. This could lead to higher sales and reduced costs involving unsuccessful authorisation attempts.
Required Action by Merchants (Mastercard mandate)
Specifically as part of the Decline Reason Code Service, merchant has to prepare to receive the field MerchantAdviceCode in responses from PXP and in combination with the value provided in the field ProviderResponseCode, modify the logic for re-trying authorisations as per the table below:
| Provider Response Code | Merchant Advice Code | Merchant Advice Description | Merchant Action |
|---|---|---|---|
| 79 or 82 | 01 | Updated information needed | Updated information found to be available in Mastercard ABU database* – secure new information before reattempting |
| 79 or 82 | 03 | Do not try again | Updated credentials were not found to be available in Mastercard ABU database* – do not retry |
| 83 | 01 | Additional information needed | Ensure card information is correct. Authentication may improve likelihood of an approval – retry using authentication (such as EMV 3DS) |
| 83 | 03 | Do not try again | Suspected Fraud – do not retry |
| 79 or 82 or 83 | 02 | Try again later | Retry transaction later |
*ABU - Might be due to the card being expired or reissued. In such cases, please ask customer to review and update card information.
A full list of MAC Codes is available at the end of this document.
Use of Original ISO Response is strongly recommended
While the text above highlights the use of the
ProviderResponseCodefield together with theMerchantAdviceCodefield, merchants are strongly recommended to rather configure and use theOriginalISOResponseCodefield ininitiatePaymentResponsein conjunction withMerchantAdviceCode.This will ensure they have the most accurate information in order to query and categorise all types of declines.
“Do not try again”
When Mastercard returns a Decline Reason Code with a “Do not try again” value, merchants must not retry such payments (for the same card, transaction and amount for a merchant within a 30 day period of the original decline).
PXP will charge fees for re-tried transactions that were previously declined authorisations with
MerchantAdviceCode"Do not try again” as imposed by MasterCard.
Example initiatePayment request and response:
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>PSD2_TestMerchant_1</merchantID>
<shopID>PSD2_TestShop_1</shopID>
<merchantTransactionID>TestReceivingMAC04</merchantTransactionID>
<paymentMethodID>1</paymentMethodID>
<amount currencyCode="EUR">30</amount>
<userID>f9651638-2f0f-4f54-ab3f-8513ea897876</userID>
<userData>
<username>f9651638-2f0f-4f54-ab3f-8513ea897876</username>
<firstname xsi:nil="true" />
<lastname xsi:nil="true" />
<currencyCode xsi:nil="true" />
<languageCode xsi:nil="true" />
<email xsi:nil="true" />
<address xsi:nil="true" />
<identificationNumberType xsi:nil="true" />
<drivingLicenseNumber xsi:nil="true" />
<drivingLicenseIssuingState xsi:nil="true" />
</userData>
<userIP>127.0.0.1</userIP>
<userSessionID>dc138506-2d2b-4d90-9cbb-92cf0879bd76</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value>dd86a2f5-e53e-4a09-ab0e-1d9de6089742</value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentDescriptionLanguageCode</key>
<value>en</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserVerificationNotificationURL</key>
<value>https://www.notification.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserLanguage</key>
<value>en</value>
</data>
<data xsi:type="keyIntValuePair">
<key>BrowserScreenHeight</key>
<value>768</value>
</data>
<data xsi:type="keyIntValuePair">
<key>BrowserScreenWidth</key>
<value>1024</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserHeaderAccept</key>
<value>BrowserHeaderAccept</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserHeaderUserAgent</key>
<value>BrowserHeaderUserAgent</value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserVerificationNotificationURL</key>
<value>https://api.test.kalixa.com/WebMockProviders/threedsv2acs/showCRes</value>
</data>
<data xsi:type="keyIntValuePair">
<key>BrowserScreenColorDepth</key>
<value>32</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrowserTimeZone</key>
<value>60</value>
</data>
<data xsi:type="keyBooleanValuePair">
<key>BrowserJavaEnabled</key>
<value>true</value>
</data>
<data xsi:type="keyBooleanValuePair">
<key>BrowserJavaScriptEnabled</key>
<value>true</value>
</data>
</specificPaymentData>
<paymentAccount>
<specificPaymentAccountData>
<data xsi:type="keyStringValuePair">
<key>CardNumber</key>
<value>5127745333482708</value>
</data>
<data xsi:type="keyStringValuePair">
<key>HolderName</key>
<value>Gergana Dimova</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryMonth</key>
<value>12</value>
</data>
<data xsi:type="keyIntValuePair">
<key>ExpiryYear</key>
<value>2030</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CardVerificationCode</key>
<value>111</value>
</data>
</specificPaymentAccountData>
</paymentAccount>
</initiatePaymentRequest>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>PSD2_TestMerchant_1</merchantID>
<shopID>PSD2_TestShop_1</shopID>
<paymentMethod>
<key>1</key>
<value>ECMC Deposit</value>
</paymentMethod>
<merchantTransactionID>TestReceivingMAC04</merchantTransactionID>
<paymentID>142b92ae-c73c-489e-8fe4-48f536ad384b</paymentID>
<userID>f9651638-2f0f-4f54-ab3f-8513ea897876</userID>
<paymentProvider>
<key>92</key>
<value>CQRUK</value>
</paymentProvider>
<amount currencyCode="EUR">30</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>b044ebbe-fa8b-4c57-a22a-b131dd62df84</id>
<definition>
<key>13</key>
<value>AuthorisedByProvider</value>
</definition>
<createdOn>2021-10-14T11:42:19.0949769Z</createdOn>
<description>Approved or completed successfully</description>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ApprovalCode</key>
<value>998793</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>true</isExecuted>
<baseAmount currencyCode="EUR">30</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ElectronicCommerceIndicator</key>
<value>07</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>MerchantAdviceCode</key>
<value>03</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>SchemeTransactionIdentifier</key>
<value>MEC7VRE10KAE</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>541aebe3-2772-4db5-a60a-39b2b58690a9</paymentAccountID>
</paymentAccount>
</payment>
</initiatePaymentResponse>
Test cases
Merchant can simulate receiving a combination of Provider Response Code and Merchant Advice Code by using the amount field as <ProviderResponseCode>.<MerchantAdviceCode> with the test card number 5101080000040039 in the initiatePayment request.
The payment will be RefusedByProvider.
Allowed combinations for testing:
- 79.01, 79.02, 79.03, 79.04, 79.21
- 82.01 ... 82.21
- 83.01 ... 83.21
Examples:
| Amount | Returned Provider Response Code | Returned Merchant Advice Code |
|---|---|---|
| 79.01 | 79 | 01 |
| 82.03 | 82 | 03 |
| 83.21 | 83 | 21 |
If a merchant wants to receive a successful response (Provider Response Code = 00 and payment state "AuthorisedByProvider"), then the below card numbers should be used, the amount field is not considered.
Combination of Provider Response Code = 00 and Merchant Advice Code
The only relevant real-world combination of Provider Response Code 00 is with Merchant Advice Code 01. All other combinations are not applicable as they will only be used for refused payments.
| MerchantAdviceCode | CardNumber to be used |
|---|---|
| 01 | 5101080000000033 |
| 02 | 5116097131686079 |
| 03 | 5127745333482708 |
| 04 | 5101080000000025 |
| 21 | 5101080000000041 |
Further guidance on MasterCard declines
In addition to the above, there is some further guidance provided by MasterCard on the topic of declines related to Merchant Advice Codes.
The most common Provider Response codes that Issuers send Merchant Advice Codes for are as follows:
• 05 – Do not honor
• 14 – Invalid card number
• 30 – Format error
• 51 – Insufficient funds/over credit limit
• 54 – Expired card
The below table shows some examples as to how these Provider Response Codes and Merchant Advice Codes should be used in conjunction with one another.
More combinations possible
The below table shows only a snapshot of possible combinations of response and decline codes. Other combinations are possible
Most important combinations and how to use them:
| Provider Response Code | Merchant Advice Code | Merchant Advice Description | Merchant Action |
|---|---|---|---|
| 00 05 14 51 54 | 01 | New account information available | Obtain new account information before next billing cycle |
| 51 | 02 | Cannot approve at this time | Recycle transaction 72 hours later |
| 51 | 24 | Retry after 1 hour | Recycle transaction 1 hour later |
| 51 | 25 | Retry after 24 hours | Recycle transaction 24 hours later |
| 51 | 26 | Retry after 2 days | Recycle transaction 2 days later |
| 51 | 27 | Retry after 4 days | Recycle transaction 4 days later |
| 51 | 28 | Retry after 6 days | Recycle transaction 6 days later |
| 51 | 29 | Retry after 8 days | Recycle transaction 8 days later |
| 51 | 30 | Retry after 10 days | Recycle transaction 10 days later |
| 05 14 15 54 | 03 | Do not try again | Obtain another type of payment from customer |
| 39 | 04 | POS cardholder presence indicator | Resubmit with appropriate information |
| 05 | 21 | Payment Cancellation | Do not submit |
Reminder: Use of the Original ISO Response field is highly recommended
List of MAC Codes
| Value | Description |
|---|---|
| 01 | New account information available |
| 02 | Cannot approve at this time, try again later |
| 03 | Do not try again |
| 04 | Token requirements not fulfilled for this token type |
| 05 | Negotiated value not approved |
| 21 | Payment Cancellation (Mastercard use only) |
| 22 | Merchant does not qualify for product code |
| 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 | Consumer non-reloadable prepaid card |
| 41 | Consumer single-use virtual card number |
For MAC Codes 40 and 41, merchants should not place such accounts on file for future use.
Updated about 2 months ago