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 <<webServicesIntegration>>. The tables below show the mapping between the two types of responses returned by the QNB ALAHLI.
| Payment Client/Virtual Payment Client | <<webServicesIntegration>> | ||
|---|---|---|---|
| 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 | <<webServicesIntegration>> | ||
|---|---|---|---|
| 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 | <<webServicesIntegration>> | ||
|---|---|---|---|
| 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 <<webServicesIntegration>> 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. For more information about Merchant Advice Codes for declined transactions, refer to Transaction Errors.