Magento 2 – Mastercard Gateway
Hosted Payment Session Configuration
This section explains the options available for configuring a Hosted Payment Session. Each option is designed to help you customize the session to suit your business needs. Follow this guide step by step to understand how to set up and personalize the Hosted Payment Session.
Enabled:
Open the dropdown menu and select “Yes” to enable the Hosted Payment Session feature. This step activates the configuration needed for this payment option as well as to enable the same in the checkout page.
Vault Enabled:
When this feature is turned on, customers have the option to save their payment information which is encrypted by Mastercard Gateway and securely stored in a digital “Vault.”
Once stored, the Vault creates a unique payment token linked to your payment method. This token acts as a safe reference for your transactions. It allows you to process payments without needing to handle or see sensitive card details directly.
By using this system, your business reduces the need to manage unencrypted payment data, which significantly lowers the effort required to meet PCI compliance standards—rules designed to keep payment data secure.
Title: Enter the name to display on the checkout page for this payment method.
Payment Action:
Choose one of the following payment flows:
1. Authorize Only
- If you choose “Payment Action” as Authorize Only, you will need to manually process the transaction to accept the payment. This means you must take an additional step to capture the payment amount.
- The manual capture of funds is done through the Backend. Detailed instructions for this process can be found in the Managing Transactions section of this document.
- The Authorize Only payment method works in two steps:
- Authorization happens during checkout. This ensures the payment method is valid and reserves the funds.
- Funds capture happens later. The money is only deducted after the merchant invoices the order.
This method gives you more control but requires you to complete the capture process manually within the stipulated timeframe configured for your MID.
2. Authorize & Capture
- If you choose the ‘Payment Action’ option as Authorize & Capture, the payment process will happen automatically. Here’s how it works:
- When a user enters their card details and submits an order, the total amount of the order is immediately deducted from their card.
- This amount is then automatically transferred to the merchant’s account.
Please note that while the transfer is automatic, it might take a little time for the amount to show up in the merchant’s account. However, no additional action is required from either the user or the merchant to complete the process.
3. Verify and Add Token to Order (VATO)
If the “Verify and Add Token to Order” option is selected for the Payment Action, the payment will be verified once the customer places the order, but the amount will not be captured. Here’s how VATO works:
- If the Payment Action is set to “Verify and Add Token to Order” the customer’s payment token will be securely saved with the order. However, the money won’t be reserved from their account at checkout. You will need to manually process the payment later to complete the transaction.
- The manual capture of funds is done through the Backend. Detailed instructions for this process can be found in the Managing Transactions section of this document.
- The stored payment token can be accessed later using the REST API for further actions or integrations.
- Note: This payment method does not support the EMV 3DS authentication option.
These configurations ensure that the appropriate tokenization and verification processes are applied based on the selected Payment Action.
Add Token to Order:
If you choose “Yes” for this option, the payment token used during the transaction will be saved securely at the order level. Once the customer places the order, the token can be accessed through the REST API.
This option will only appear if you select “Authorize Only” or “Authorize and Capture” as your payment action. Make sure one of these is chosen to enable this feature.
Authentication Type:
Select the method you want to use:
- API Username: Enter the API username provided to you. This is typically shared when you set up your merchant account for integrations.
- API Password: Enter the API password that comes with your API username. You can find this password in your merchant account.
2. SSL Certificate
- API Username: This is the unique identifier you will use to access the API.
- SSL Certificate: A special digital certificate that ensures secure communication. It must be issued by a Certificate Authority (CA) approved by Mastercard.
- SSL Key: A private key that works with the SSL Certificate to keep your data safe.
- Custom PKI Gateway URL: This is a unique web address provided by your payment service provider/bank. You’ll need to contact them to get this URL.
You must present a certificate to authenticate yourself to the Mastercard Gateway with certificate authentication. Certificates are typically issued from one of many organizations that act as Certificate Authorities (CAs). This model of authentication is a component of Public Key Infrastructure (PKI) where security is achieved through confidentiality, integrity, non-repudiation, and authentication.
Gateway:
Choose the gateway that matches your account’s region.
Custom Gateway URL:
If you choose “Other” as the gateway option, you’ll need to provide a custom URL. This custom URL will replace the default gateway assigned to your region.
WebHook Secret:
Enter the WebHook secret from your merchant account. To find this, check the “API Configuration” section under Obtaining Webhook Secret.
WebHook URL:
Provide the WebHook URL linked to your merchant account. This is where you will receive WebHook notifications.
- Select “Yes” to use test credentials (your API username will start with “TEST”).
- Choose “No” to switch to live production mode.
- Tip: Always test in Test mode before switching to Live mode to ensure everything works correctly.
Debug:
Enable Debug by selecting Yes if you’re testing in Test Mode. Debugging creates detailed logs that can help you identify and fix any issues with your payment process.
New Order Status:
This setting determines how successfully placed orders are labeled in the Magento Platform after being processed. You can choose from three options:
- Payment Verified: The payment has been confirmed.
- Processing: The order is being handled.
- Suspected Fraud: The order appears suspicious and may need review.
Changing this setting won’t impact how transactions are processed by the payment gateway—it only updates how they are displayed in your system.
Enable 3-D:
This option lets you select the security level for the user’s card during transactions. Here’s what each level means:
- Disabled:
- If you choose this option, the order will be processed once the card details and the order itself are verified.
- No additional steps, such as entering a password or PIN, will be required from the payer.
- 3-D Secure:
- This level adds an extra layer of security.
- The cardholder must authenticate themselves by entering a password they previously registered with their card issuer.
- It uses secure authentication schemes like:
- Mastercard SecureCode™
- Verified by Visa™
- American Express SafeKey™
- J/Secure™
- Diners Club ProtectBuy™
- EMV 3-D Secure (3DS2):
- This is the latest and more advanced version of 3-D Secure.
- It improves security and reduces interruptions for low-risk transactions.
- Here’s how it works:
- The card issuer’s Access Control Server (ACS) assesses the transaction risk using details like merchant-provided data, browser fingerprinting, or past interactions with the payer.
- If the transaction is low-risk, it proceeds smoothly without asking for additional input.
- For higher-risk transactions, the payer may need to complete a challenge, such as entering a PIN or answering a security question.
- Supported schemes include:
- Mastercard SecureCode™
- Verified by Visa™
- American Express SafeKey™
- JCB J/Secure™
- Diners Club/Discover ProtectBuy™
Accepted Currency:
Choose the currency you want to use as the base for your store. This determines the default currency for transactions.
Credit Card Verification:
- Set this to Yes if you want to require card verification for Hosted Payment Sessions.
- Card verification ensures the card details are valid and belong to the payer.
This will work only if the CCV is enabled in the MID
Require CCV for Tokenized Card Transactions:
- Set this to Yes to mandate card verification (using the CCV/CVV code) for saved cards during transactions.
- This adds an extra layer of security for tokenized (saved) cards.
Payment from Applicable Countries:
Merchants can decide which countries they want to accept payments from. This setting works separately from any blocking rules set in the Merchant Manager.
You have two choices:
- All Allowed Countries: Payments can be processed from all countries that are allowed.
- Specific Countries: You can pick certain countries from which payments will be accepted.
Send Line Items:
Select Yes if you want to include detailed order information (like item names, quantities, and prices) in the transactions sent to the Mastercard Gateway. This helps with tracking and provides more details for reporting.
Sort Order:
This controls the order in which this payment method appears to customers. A lower number means higher priority (e.g., 0 is the top priority).
Advanced Configuration:
In the Advanced configuration section, you can find information about the current API version utilized by the Mastercard Gateway plugin. Additionally, there is a field available to Create Token Request Data, Authorize Request Data, Sale Request Data & Verify Request Data.