MasterCard Decline Reason Code Service

MasterCard has introduced a new Decline Reason Code Service for Card Not Present (CNP) payments as of November 2nd, 2021. Moto and Card Present (CP) payments are out of scope.

This Service will provide enhanced information about transaction declines while mandating some changes to Issuer usage of the standard 05 – Do Not Honor responses.

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.

📘

Applies to Mastercard Transactions only

The Decline Reason Code Service is a Mastercard only service!

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.

❗️

“Do not try again”

When Mastercard returns a Decline Reason Code with a “Do not try again” value, merchant must not retry such payments (for the same card, transaction and amount for a merchant within a 30 day period of the original decline).
These will be monitored and assessed by MasterCard and it is expected that this guidance will be followed.
Starting from 25th February 2022, PXP will start charging fees to the merchant for re-tried transactions with previously declined authorisations with MerchantAdviceCode "Do not try again” as imposed by MasterCard.

Example initiatePayment request:

<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>

Example initiatePayment response:

<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>

Testcases

Merchant can simulate to receive 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

In live, the only relevant or applicable 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. Basically any combination is possible on live and can be used by the issuers.

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