Troubleshooting & FAQs

This section contains suggestions and solutions to problems that may occur with your integration.

How long will an authorization be valid on a payer account?

This depends on the financial institution who issued the card to the payer. Each card issuer defines the authorization expiry period in which they hold the funds on the payer's account, while they wait for the arrival of the capture transaction. Generally it is 5-8 processing days, before the authorization purges from the payer account and access to the funds are released back to the payer.

How are card details from multiple sources (tokens, payment sessions) combined in requests?
How do I parse validation errors if I wish to display graceful messages to my payers?

You can use the following fields to catch validation errors:

The field error.explanation [REST][NVP] will contain some human readable error text giving further information about the error, such as minimum or expected length, etc. Do not parse this information as the format for this text cannot be guaranteed.

How are the Payment Client and Virtual Payment Client response codes mapped to API?

Integrations with Payment Client and Virtual Payment Client return response codes unlike the enumerations returned for API. The tables below show the mapping between the two types of responses returned by the MasterCard Payment Gateway.

Transaction Response Codes
Payment Client/Virtual Payment Client API
Response Code Description response.gatewayCode Description
0 Transaction Successful APPROVED Transaction Approved
1 Transaction could not be processed UNSPECIFIED_FAILURE Transaction could not be processed
2 Transaction Declined - Contact Issuing Bank DECLINED The requested operation was not successful. For example, a payment was declined by issuer or payer authentication was not able to be successfully completed.
3 Transaction Declined - No reply from Bank TIMED_OUT Response timed out
4 Transaction Declined - Expired Card EXPIRED_CARD Transaction declined due to expired card
5 Transaction Declined - Insufficient Credit INSUFFICIENT_FUNDS Transaction declined due to insufficient funds
6 Transaction Declined - Bank system error ACQUIRER_SYSTEM_ERROR Acquirer system error occured processing the transaction
7 Payment Server Processing Error. Typically caused by invalid input data such as a credit card number. Processing errors can also occur. SYSTEM_ERROR Internal system error occurred processing the transaction
8 Transaction Declined - Transaction Type not supported NOT_SUPPORTED Transaction type not supported
9 Bank Declined Transaction (Do not contact Bank) DECLINED_DO_NOT_CONTACT Transaction declined - do not contact issuer
A Transaction Aborted ABORTED Transaction aborted by card holder
B Transaction Blocked -Returned when:
-the Verification Security Level has a value of '07',
- The merchant has 3D-Secure blocking enabled,
-the overall risk assessment result returns a 'Reject' or 'System Reject'
BLOCKED Transaction blocked due to Risk or 3D Secure blocking rules
C Transaction Cancelled CANCELLED Transaction cancelled by card holder
D Deferred Transaction DEFERRED_TRANSACTION_RECEIVED Deferred transaction received and awaiting processing
E Transaction Declined - Refer to card issuer REFERRED Transaction declined - refer to issuer
F 3D Secure Authentication Failed AUTHENTICATION_FAILED 3D Secure authentication failed
I Card Security Code Failed INVALID_CSC Invalid card security code
L Shopping Transaction Locked. This indicates that there is another transaction taking place using the same shopping transaction number. LOCK_FAILURE Order locked - another transaction is in progress for this order
M Transaction Submitted (the transaction has been directed to the acquirer, but the Payment Server has not yet received it to complete the transaction) SUBMITTED Transaction submitted - response has not yet been received
N Cardholder not enrolled in 3DSecure (authentication only) NOT_ENROLLED_3D_SECURE Card holder is not enrolled in 3D Secure
P Transaction is Pending PENDING Transaction is pending
R Retry Limits Exceeded, Transaction Not Processed EXCEEDED_RETRY_LIMIT Transaction retry limit exceeded
S Transaction Declined - Duplicate Batch DUPLICATE_BATCH Transaction declined due to duplicate batch
T Address Verification Failed DECLINED_AVS Transaction declined due to address verification
U Card Security Code Failed DECLINED_CSC Transaction declined due to card security code
V Address Verification and Card Security Code Failed DECLINED_AVS_CSC Transaction declined due to address verification and card security code
W Transaction Declined - Payment Plan not supported. DECLINED_PAYMENT_PLAN Transaction declined due to payment plan
X Approved pending settlement - Approved by a batch settlement system, but still awaiting further details from the acquirer. APPROVED_PENDING_SETTLEMENT Transaction Approved - pending batch settlement
? Response unknown UNKNOWN Response unknown
Address Verification Service(AVS) Response Codes
Payment Client/Virtual Payment Client API
Response Code Description response.cardholderVerification.avs.gatewayCode Description
X Exact match – address and 9 digit ZIP/postal code ADDRESS_ZIP_MATCH Street address and zip/postcode were matched
Y Exact match – address and 5 digit ZIP/postal code
D Street Address and postal code match for international transaction.
M Street Address and postal code match for international transaction.
F Street address and postal code match. Applies to U.K. only.
W 9 digit ZIP/postal code matched, Address not Matched ZIP_MATCH Zip/postcode matched. Street address not matched
P Postal Codes match for international transaction but street address not verified due to incompatible formats.
Z 5 digit ZIP/postal code matched, Address not Matched
A Address match only ADDRESS_MATCH Street address matched
B Street Address match for international transaction. Postal Code not verified due to incompatible formats.
S Service currently not supported. SERVICE_NOT_SUPPORTED Service currently not supported by acquirer or merchant
G International transaction, address information unavailable. NOT_VERIFIED AVS could not be verified for an international transaction
C Street Address and Postal Code not verified for International Transaction due to incompatible formats.
I Visa Only. Address information not verified for international transaction.
R Issuer system is unavailable. Retry. SERVICE_NOT_AVAILABLE_RETRY Issuer system is unavailable. Retry can be attempted
U Address unavailable, no data from Issuer. NOT_AVAILABLE No data available from issuer or AVS data not supported for transaction
E Not a mailphone order.
N Address and ZIP/postal code not matched NO_MATCH No match
0 (Zero) No AVS requested. (Used by VisaII.) NOT_REQUESTED AVS not requested
K Card holder name only matches. NAME_MATCH Card holder name matched
O Card holder name and address matches NAME_ADDRESS_MATCH Card holder name and address matched
L Card holder name and zip/postcode matches NAME_ZIP_MATCH Card holder name and zip/postcode matched
Card Security Code (CSC) Response Codes
Payment Client/Virtual Payment Client API
Response Code Description response.cardSecurityCode.gatewayCode Description
M Valid or matched CSC MATCHED Valid or matched
S Merchant indicates CSC not present on card NOT_PRESENT Merchant indicated CSC not present on card
P CSC Not Processed NOT_PROCESSED Not processed
U Card Issuer is not registered and/or certified NOT_SUPPPORTED Card Issuer is not registered and/or certified
N Code invalid or not matched NO_MATCH Invalid or not matched.
Can I resubmit a request to the MasterCard Payment Gateway if I don't receive a response?

Yes, it's safe to resubmit a request with the exact same details because the gateway supports idempotent operations. Idempotent operations produce the same result when invoked repeatedly. If the gateway has already received your request, it will return the original response; otherwise it will process the request and return the response.

How can I match up requests to the MasterCard Payment Gateway with responses?

Typically, you can match up requests to responses using and fields as these are provided in the requests and returned in the responses. However, if your application does not support a synchronous integration model or your source and target for a request differ, you can use the field correlationId to identify the request and its matching response. correlationId is a transient identifier, the value for which does not persist in the gateway and is returned as provided in the response to the request. You can use the correlationId with all API requests.

Why am I getting No merchant acquirer link error for an acquirer I am configured for?

Please contact your payment service provider to make sure your merchant acquirer link on the gateway is configured for the required card type and currency combinations.

What is Merchant Administration?

Merchant Administration is a web-based interface that allows merchants to easily view and manage their orders. The merchants can search and view their order/transaction details, download CSV reports, check 3-D Secure results, set up risk controls, create orders manually, manage refunds, and much more. Refer to Merchant Administration User Guide for more details.

Merchants need to be boarded on the gateway and have their merchant profile configured successfully to access Merchant Administration.

What if my transaction gets declined?

The issuer or card network may provide additional information in the form of a Merchant Advice Code, which will help you understand the reason for declining the transaction. When a transaction is declined for insufficient funds, the advice code may recommend a retry time frame to merchants in which an authorization approval is likely to be successful.

The following table provides a description of the various merchant advice codes returned by the schemes.

Merchant Advice Code Scheme Recommendation
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
22 Merchant does not qualify for product code
24 Retry after 1 hour
25 Retry after 24 hours
26 Retry after 2 days
27 Retry after 4 days
28 Retry after 6 days
29 Retry after 8 days
30 Retry after 10 days
R0 Stop Payment Order
R1 Revocation of Authorization Order
R3 Revocation of All Authorizations Order

Copyright © 2023 MasterCard