Skip to content

Magento 2 - MasterCard Payment Gateway Services

OnTap Magento - MasterCard Payment Gateway Services

Version compatibility

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:

Installation

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

Upgrading

To install the latest version of the module, use the following command:

composer.phar update

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.

Configuration

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.

OnTap Magento - MasterCard Payment Gateway Services)

As you may see, this tab contains three separate methods.

Integration Model

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.

OnTap Magento - MasterCard Payment Gateway Services

The example of the Hosted Checkout Popup

II. Hosted Session Integration

Choose the Hosted Session model if you want control over the layout and styling of your payment page, while reducing PCI compliance costs. The Hosted Session JavaScript client library enables you to collect sensitive payment details from the payer in payment form fields, sourced from and controlled by Mastercard Payment Gateway. The gateway collects the payment details in a payment session and temporarily stores them for later use. You can then include a payment session in place of payment details in the transaction request to process a payment.

OnTap Magento - MasterCard Payment Gateway Services

The example of the 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.

OnTap Magento - MasterCard Payment Gateway Services

The example of the ACH Integration

Hosted Checkout Configuration

I

OnTap Magento - MasterCard Payment Gateway Services

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

  • Authorize & Capture

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.

  • Authorize Only

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.

II

OnTap Magento - MasterCard Payment Gateway Services

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.

Test Mode

We highly recommend you to configure your Merchant credentials in TEST mode beforehands and make sure that everything works.

III

OnTap Magento - MasterCard Payment Gateway Services

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.

Advanced Configuration

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:

OnTap Magento - MasterCard Payment Gateway Services

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:

OnTap Magento - MasterCard Payment Gateway Services

I "Payment Action" is not required to be defined so omitted from the configurations.

II "Payment Modal Title" is not required and not available.

Managing Transactions

Online Capture

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:

OnTap Magento - MasterCard Payment Gateway Services

  • On the New Invoice page, ensure that the Capture Online option is selected from the Amount dropdown menu:

OnTap Magento - MasterCard Payment Gateway Services

  • Click the Submit Invoice button.

This will then initiate a FULFIL transaction to MasterCard Payment Gateway Services.

Frauds

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.

OnTap Magento - MasterCard Payment Gateway Services

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:

OnTap Magento - MasterCard Payment Gateway Services

If, however, a transaction requires a risk review, this will be indicated as REVIEW_REQUIRED:

OnTap Magento - MasterCard Payment Gateway Services

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:

OnTap Magento - MasterCard Payment Gateway Services

Gatekeeper Review

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.

Refund/Credit Memo

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.

OnTap Magento - MasterCard Payment Gateway Services

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

OnTap Magento - MasterCard Payment Gateway Services

Refund button

Note that the Refund Offline option will not initiate a refund through MasterCard Payment Gateway Services

API Configuration

To find and set up the credentials, please login to your MasterCard Merchant Administration interface.

API Password

To obtain an API password, you need to enable integration access via password.

Once logged in your merchant account, select Admin → Integration Settings

API - MasterCard Payment Gateway Services

Click the Edit button on the Integration Settings page:

API - MasterCard Payment Gateway Services

The Integration Authentication Passwords workspace will appear, you will need to click Generate New button next to Password 1:

API - MasterCard Payment Gateway Services

Once the password has been generated, select the Enable Integration Access Via Password checkbox, copy the password and click the Submit button.

Webhook Secret

To obtain the Webhook Secret, you need to enable integration access via password.

Once logged in in the merchant account, select Admin → Webhook Notifications

API - MasterCard Payment Gateway Services

On the Webhook Notifications page:

  1. Select the Enabled checkbox.
  2. Select JSON/REST from the Web Services API Format drop-down list.
  3. Copy the Notification Secret (it will be used for the MasterCard Payment Gateway Services extension).
  4. Click the Save button.

API - MasterCard Payment Gateway Services

The notification URL is not used for this integration.

Internal Testing

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.

  1. 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
  2. Declined Authorization

    • Ensure declined transactions have the correct state in the Magento Admin Panel.
  3. 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
  4. Submit a full refund for a invoiced order

    • Ensure you can perform a successful refund for the full amount of the order.
    • Ensure the transaction is showing the correct state in both Magento Admin Panel and Merchant Administration
  5. Submit a partial refund for an invoiced order

    • Ensure you can perform a successful refund for a partial amount of the full order.
    • Ensure the transaction is showing the correct state in both Magento Admin Panel and Merchant Administration
  6. 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.

Support

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.