Troubleshooting & FAQs
This section contains suggestions and solutions to problems that may occur with your integration.
The surcharging functionality on Mastercard Gateway allows a merchant to apply a surcharge on a transaction based on the following parameters:
- Gateway entry point such as Hosted Checkout or API.
- Payment method such as Mastercard, Visa, or American Express.
- Funding method such as Credit or Debit.
- Currency
Yes, you can configure the IP Country filtering rules in Merchant Administration. Your payment service provider can configure rules for you in Merchant Manager, in addition to rules that apply to all their merchants. This will allow you to reject or review transactions that originate from the IP addresses associated with high-risk countries.
Refunds can be performed only when a funds transfer is completed either through a Pay or a Capture.
Void (Cancel) can be performed only on transactions that have not been sent to the bank by the acquirer for processing at the end of the day.
Yes, you can set a recurring payment with a variable amount, for example, payment of post-paid bills. You need to update the amountVariability parameter value according to the requirements. For more information, see Credential On File Transactions.
The main difference between the two SDK versions are as follows:
| SDK version 1 | SDK version 2 |
|---|---|
| No native in-app experience | Native in-app experience, without redirects |
| Challenge flow with redirects | Multiple challenge flows such as OTP, single and multi-select, answer-based are supported. |
| Issuer challenge flow through web browser on a mobile device | Smarter frictionless flow that leads to lesser challenges for payer |
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.
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.
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 Gateway.
| 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 occurred 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 |
| 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 |
| 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 does not present on card. | NOT_PRESENT |
Merchant indicated CSC does 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 |
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.
Typically, you can match up requests to responses using order.id and transaction.id 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.
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.
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.
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.
| Mastercard | |
|---|---|
| Mastercard 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 |
| 40 | Consumer non-reloadable prepaid card |
| 41 | Consumer single-use virtual card number |
| 43 | Consumer multi-use virtual card number |
| Visa | |||
|---|---|---|---|
| Visa Merchant Advice Code | Visa Response Code | Definition of Visa Response Code | Reattempt Allowed |
| 00 | 00 | Approval and completed successfully Accepted and processed | No |
| 03 | 03 | Invalid merchant | Yes, Reattempt up to 15 times over 30 days. |
| 04 | 04 | Pick up card | No |
| 05 | 05 | Do not honor | Yes, Reattempt up to 15 times over 30 days. |
| 07 | 07 | Pick up card, special condition | No |
| 10 | 10 | Partial Approval | N/A |
| 12 | 12 | Invalid transaction | No |
| 13 | 13 | Invalid amount or Currency conversion field overflow | Yes, Reattempt up to 15 times over 30 days. |
| 14 | 14 | Invalid Account Number | No |
| 15 | 15 | No such issuer | No |
| 19 | 19 | Re-enter transaction | Yes, Reattempt up to 15 times over 30 days. |
| 39 | 39 | No Credit Account | Yes, Reattempt up to 15 times over 30 days. |
| 41 | 41 | Lost Card | No |
| 43 | 43 | Stolen Card | No |
| 46 | 46 | Closed Account | No |
| 51 | 51 | Funds related | Yes, Reattempt up to 15 times over 30 days. |
| 52 | 52 | No checking account | Yes, Reattempt up to 15 times over 30 days. |
| 53 | 53 | No Savings Account | Yes, Reattempt up to 15 times over 30 days. |
| 55 | 55 | Invalid PIN | Yes, Reattempt up to 15 times over 30 days. |
| 57 | 57 | Transaction not permitted to cardholder | No |
| 58 | 58 | Transaction not allowed at terminal | Yes, Reattempt up to 15 times over 30 days. |
| 59 | 59 | Suspected Fraud | Yes, Reattempt up to 15 times over 30 days. |
| 61 | 61 | Exceeds approval amount limit | Yes, Reattempt up to 15 times over 30 days. |
| 62 | 62 | Restricted card | Yes, Reattempt up to 15 times over 30 days. |
| 65 | 65 | Exceeds withdrawal frequency limit | Yes, Reattempt up to 15 times over 30 days. |
| 70 | 70 | PIN data required | Yes, Reattempt up to 15 times over 30 days. |
| 74 | 74 | Different value than that used for PIN encryption errors | Yes, Reattempt up to 15 times over 30 days. |
| 75 | 75 | Allowable number of PIN-entry tries exceeded | Yes, Reattempt up to 15 times over 30 days. |
| 76 | 76 | Unsolicited reversal—reversal with no original transaction in history. V.I.P. unable to match reversal request to an original message | Yes, Reattempt up to 15 times over 30 days. |
| 78 | 78 | “Blocked, first used”— Transaction from new cardholder, and card not properly unblocked | Yes, Reattempt up to 15 times over 30 days. |
| 80 | 80 | No financial impact (used in reversal responses to decline originals) | Yes, Reattempt up to 15 times over 30 days. |
| 81 | 81 | Cryptographic error found in PIN (used for cryptographic error condition found by security module during PIN decryption) | Yes, Reattempt up to 15 times over 30 days. |
| 82 | 82 | Negative Online CAM, dCVV, iCVV, or CVV results, or offline PIN authentication interrupted | Yes, Reattempt up to 15 times over 30 days. |
| 85 | 85 | No reason to decline a request for address verification, CVV2 verification, or credit voucher or merchandise return | N/A |
| 86 | 86 | Cannot verify PIN; for instance, no PVV | Yes, Reattempt up to 15 times over 30 days. |
| 91 | 91 |
|
Yes, Reattempt up to 15 times over 30 days. |
| 92 | 92 | Financial institution or intermediate network facility cannot be found for routing (receiving institution ID invalid) | N/A |
| 93 | 93 | Transaction cannot be completed violation of law. | Yes, Reattempt up to 15 times over 30 days. |
| 94 | 94 | Duplicate transmission. Transaction submitted containing values in tracing data fields that duplicate values in a previously submitted transaction. | N/A |
| 96 | 96 | System malfunction | Yes, Reattempt up to 15 times over 30 days. |
| 1A | 1A | Additional customer authentication required | Yes, Reattempt up to 15 times over 30 days. |
| 6P | 6P | Verification data failed | Yes, Reattempt up to 15 times over 30 days. |
| N0 | N0 | Force STIP. Issuers can respond with this, which routes transaction to STIP. Issuers use code when they cannot perform authorization but want STIP to perform it. | Yes, Reattempt up to 15 times over 30 days. |
| N3 | N3 | Cash service not available | Yes, Reattempt up to 15 times over 30 days. |
| N4 | N4 | Cash request exceeds issuer or approved limit | Yes, Reattempt up to 15 times over 30 days. |
| N7 | N7 | Decline for CVV2 failure | Yes, Reattempt up to 15 times over 30 days. |
| N8 | N8 | Transaction amount exceeds pre-authorized approval amount | N/A |
| R0 | R0 | Stop payment order | No |
| R1 | R1 | Revocation of authorization order | No |
| R2 | R2 | Transaction does not qualify for Visa PIN | N/A |
| R3 | R3 | Revocation of all authorizations order | No |
| Z3 | Z3 | Unable to go online; offline declined | Yes, Reattempt up to 15 times over 30 days. |