Magento 2 - 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:

• extension's version 103.* supports Magento 2.3 and 2.4:

  • Magento Marketplace;

  • GitHub;

• extension's version 102.* supports Magento 2.1 and 2.2:

  • GitHub.

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.

Feature Support

Magento 2 Mastercard Payment Gateway Service module supports following list of features:

• Card payments
• Alternative payment methods
• Hosted Session
• Hosted Checkout
• Full refunds
• Partial refunds
• AVS
• 3DSv1
• 3DSv2
• ACH
• Tokenisation (Only for Hosted Payment Session method)
• Certificate based authentication
• Verify and Tokenize (Only for ACH Payment method)

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.

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.

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.

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.

Authentication Type

The module provides two different types of Authentication methods. These authentication types are available for all three integration models.

I. Login and Password

In this authentication type, you must enter the User Name and Password you obtained from your Mastercard account provider/bank.

The information on how to obtain the API credentials in the MasterCard merchant account can be found a bit later in this document.

II. Certificate Authentication

Instead of UserName and Password, an SSL certificate can be used. When this option is selected under Authentication Type, the admin panel will need to submit the following information:

• API Username
• SSL Certificate
• SSL Key
• Custom PKI Gateway URL: You will need to contact your payment service provider/bank to receive Custom PKI Gateway URL for Certificate Authentication.

Hosted Checkout Configuration

I

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

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.

III

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:

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

There are two different Payment Actions (payment flows):

• Pay

The transaction will be done automatically if Pay has been selected for Payment Action. After the user has entered the card detail and submitted Order, the total Order amount will be deducted from the user's card. It will be automatically transferred to the merchant's account. The Order will be marked with status Processing, and Invoice will be generated. It may take some time to reflect the amount into the merchant's account, but the process will be automatic.

For Pay payment Action, there is another configuration option:

Add Token to Order = If yes is selected, the received payment token will be stored on the Order level and available via REST API after the customer has placed Order.

The payment token value gets stored under the mastercard_payment_token attribute on the order level. Below is an example of an API response of an order where you can see the stored token value.

• Verify and Add Token to Order

If the Verify and add token option has been selected for Payment Action, then once the customer places Order, the payment will be verified, but the amount will not be captured. The received payment token will be stored at the order level, and also it will be available via REST API. The Order status will remain as Payment Verified, and no invoice will be generated. Also, in this scenario, Magento admin can only generate offline Invoice.

Use of Payment Token

Merchant can use the stored payment token to capture payment. So in the case when the payment does not need to be taken from the customer when they place an Order, or there is some additional payment required, the merchant can use the payment token that is available via REST API and capture payment.

The rest of the ACH payment method configurations are the same configurations as the Hosted Checkout. The only difference is that "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:

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

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.

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:

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.

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

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

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.

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

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.

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.