Magento 2 - MasterCard Payment Gateway Services
The MasterCard Payment Gateway Services Magento extension is compatible with the following Magento platforms:
- Community/Open Source Edition
- Enterprise/Commerce/Cloud Edition
As for the version of Magento:
extension's version 103.* supports Magento 2.3 and 2.4:
extension's version 102.* supports Magento 2.1 and 2.2:
Installing from Magento Marketplace
Please refer to this guide.
Installing from GitHub
Please use the following command:
composer.phar config repositories.ontap vcs https://github.com/OnTap/module-mastercard
To install the latest version of the module, use the following command:
Alternatively, if you have installed using the Magento Marketplace, you can use this information.
Make a backup!
Direct installation of Magento extensions onto your production web site is not recommended or supported. We advise you to install this on a development version of your web site first to ensure correct operation with your particular Magento installation.
In addition, we advise you to make a complete backup of your Magento system (application files and database) before proceeding.
To access the configuration of the module, select Stores → Configuration → SALES → Payment Methods from within the admin panel.
The extension adds the Mastercard Payment Gateway Services tab.
As you may see, this tab contains three separate methods.
The module supports 3 different ways of integration, either Hosted Checkout or Hosted Payment Session.
The Hosted Checkout model allows you to collect payment details from your payer through an interaction hosted and displayed by the Mastercard Payment Gateway. With this model of integration, you never see or handle payment details directly because these are collected by the hosted payment interface and submitted directly from the payer's browser to the Mastercard Payment Gateway.
I. Hosted Checkout Popup
If Hosted Checkout is integrated and enabled for Mastercard Payment Gateway module, then once user will enter required card details on popup and click on submit order, then upon successfully authorization of entered card details, funds will be deducted from user’s account and will be automatically transferred to merchant/seller’s account. It may take some time to get funds credited but this process will be automatic.
II. Hosted Session Integration
III. Automated Clearing House (ACH) Integration
The module now officially supports Automated Clearing House (ACH) as a method of integration. ACH is an electronic bank-to-bank payment type in the US. Much like the Hosted Session, as the payment method is intergrated directly into the Magento checkout, you have full control over the layout and styling of the form and follows PCI guidelines. Please note, ACH is only accepted in the US.
Hosted Checkout Configuration
First of all, you need to Enable the extenion to use it as your Magento payment method.
There are two different Payment Actions (payment flows):
- Purchase (Pay)
If Purchase has been selected for Payment Model, then transaction will be done automatically. After user has entered card detail and submit order, amount of total order will be deducted from user’s card and will be automatically transferred to merchant’s account. It may take some time for reflecting amount into merchant’s account, but the process will be automatic.
If Authorize Only has been selected for Payment Model, then merchant will have to manually process transactions and accept payment amount. Manually process of capturing funds can be done via backend and will be covered later in this document
The text specified in the Title section will appear on front-end checkout page and the Payment Modal Title is shown on the payment modal.
The information on how to obtain the API credentials in the MasterCard merchant account can be found a bit later in this document.
If the credentials are incorrect for any reason, there will be a warning displayed on the top of the configuration page.
If merchant credentials are not configured correctly, you can not enable this payment method.
The Gateway Instance should be selected based on your account region. It's possible to select the Other option and specify the Custom URL for this in the option below.
We highly recommend you to configure your Merchant credentials in TEST mode beforehands and make sure that everything works.
The Debug setting, if enabled, provides the additional output in the Magento extension for payment processes.
The New Order Status configures the order workflow if the customer chooses the MasterCard Payment Gateway Service for the purchase. Two options are available: Processing or Suspected Fraud.
The Accepted Currency handles the base currency of the store.
If needed, the store owner can limit the number of countries (or allow only several countries for the purchases), if the account has some country-specific limitations. For this, they can choose the particular countries in the Payment from Specific Countries option.
The Send Line Items setting allows the administrator choosing the shopping cart data (like product information, grand total, etc.) to be sent to MasterCard merchant or not.
The store owner can choose the Sort order of the payment method if the store has several payment methods enabled. 0 is the highest priority.
Shows API version used.
Hosted Session Configuration
The Hosted Session setup has the same configurations as the Hosted Checkout.
You can find 3 extra options here:
Enable 3-D Secure allows the store owner to handle the 3DS and 3DSv2 cards (if this configuration is enabled in the merchant account).
Credit Card Verification makes the CCV field required on the Hosted Session workspace
Require CCV for tokenized card transactions adds the CCV field for saved cards.
Automated Clearing House Integration
The ACH setup has the same configurations as the Hosted Checkout. However, there are a few differenced to note:
I "Payment Action" is not required to be defined so omitted from the configurations.
II "Payment Modal Title" is not required and not available.
If transactions have been processed as Authorise-only, they will be settled only when the order has been manually invoiced.
To manually invoice an order, please do the following:
- Locate and open the order
- Select Invoice from the top right:
- On the New Invoice page, ensure that the Capture Online option is selected from the Amount dropdown menu:
- Click the Submit Invoice button.
This will then initiate a FULFIL transaction to MasterCard Payment Gateway Services.
If GateKeeper:2.0 fraud screening is enabled on your account, each transaction will be allocated a score based on its risk profile.
You can view this information for any transaction by viewing the order, then clicking the Show Payment Details button.
If a transaction is not deemed to be a fraud risk, you will be able to issue an invoice for it immediately.
This is the case when the risk status is indicated as ACCEPTED:
If, however, a transaction requires a risk review, this will be indicated as REVIEW_REQUIRED:
A review of the transaction must then occur in Gatekeeper, where more information is available to help the merchant decide whether to accept or reject it.
If the merchant attempts to invoice the transaction before this has occurred, an error will be displayed and no invoice will be created:
For transactions requiring review, it will only be possible to invoice and complete the transaction once the transaction has been approved in Gatekeeper.
If a transaction is rejected in Gatekeeper, this will update the decision information in Magento for the order.
Refer to the Gatekeeper user manual for more information.
You can perform a refund in Magento by creating a credit memo. The refunds are available for the Invoices only.
From the list of invoices stored in Sales → Invoices, select the one you want to refund.
When the invoice opens, click the Credit Memo button.
The New Memo page opens. It looks similar to the Completed Order page, with an Items to Refund section that lists each item from the invoice.
Adjust the refund quantities and totals, then click Refund.
Note that the Refund Offline option will not initiate a refund through MasterCard Payment Gateway Services
To find and set up the credentials, please login to your MasterCard Merchant Administration interface.
To obtain an API password, you need to enable integration access via password.
Once logged in your merchant account, select Admin → Integration Settings
Click the Edit button on the Integration Settings page:
The Integration Authentication Passwords workspace will appear, you will need to click Generate New button next to Password 1:
Once the password has been generated, select the Enable Integration Access Via Password checkbox, copy the password and click the Submit button.
To obtain the Webhook Secret, you need to enable integration access via password.
Once logged in in the merchant account, select Admin → Webhook Notifications
On the Webhook Notifications page:
- Select the Enabled checkbox.
- Select JSON/REST from the Web Services API Format drop-down list.
- Copy the Notification Secret (it will be used for the MasterCard Payment Gateway Services extension).
- Click the Save button.
The notification URL is not used for this integration.
Once you have successfully configured your Magento Mastercard Payment Gateway Service, a few basic tests should be performed to make sure your implementation is working as expected. The scenarios that follow should be considered the minimum level of testing and MasterCard Payment Gateway Services encourage the creation of your own test scenarios that suit your specific business needs.
To access the MasterCard Payment Gateway test simulator, ensure gateway mode is set to TEST. The test simulator is configured to generate predictable results based on the transaction request and card details you supply.
You can trigger specific transaction responses, for example the MasterCard Payment Gateway Response Code and Card Security Code validation, as well as Address Verification response codes. You can also test features like Risk Management and Wallet functionality. Details of test cards can be found here.
Successful Authorization including 3D Secure
- Ensure you can perform a successful transaction through the Magento checkout.
- Ensure the transaction is showing the correct state in both Magento Admin Panel and Merchant Administration
- Ensure declined transactions have the correct state in the Magento Admin Panel.
Create an Invoice & Capture Online
- Create an invoice from an authorized transaction.
- Ensure the transaction is showing the correct state in both Magento Admin Panel and Merchant Administration
Submit a full refund for a invoiced order
- Ensure you can perform a successful refund for the full amount of the order.
Submit a partial refund for an invoiced order
- Ensure you can perform a successful refund for a partial amount of the full order.
Refund, Capture, Void via Merchant Administration
- In some business scenarios it may be necessary to undertake certain actions via Merchant Administration. It is possible (with the correct user privileges) to perform refunds, voids and captures via the Gateway Interface.
- You should ensure you have sufficient business processes in place to manually update the order state in Magento where necessary.
If you have completed all of the configuration steps above, but are not able to successfully process transactions, you may need to contact your Integrator.