Implementing a Direct Payment Integration

Prerequisites

Integration Steps

Do not invoke any API operation directly from the browser.

Step 1: Access the gateway

As a first step, check your connectivity to the Mastercard Payment Gateway.

Step 2: Knowing Your Input Fields

Before you start building the integration, you must be prepared with the values for the fields that require your input.

Step 3: Create the Transaction Request

Creating the body of the request is a critical step in the integration.

Step 4: Send the Transaction Request

There are many components to making sure the transaction request is sent securely to the Mastercard Payment Gateway.

Step 5: Process the Transaction Response

Once a transaction request has been sent to the gateway, you will generally receive a response within a very short period. You will need to process this in order to complete the transaction.

Step 6: Test and Go Live

Testing allows you to check if your integration is working as desired.

Troubleshooting and FAQs

How do I know what the latest version of the API is?

Go to the appropriate (REST/NVP) [all versions] link in the Protocol Documentation section on the API Reference index page.

Are the API field names case-sensitive?

Yes, the API field names for all operations are case-sensitive.

How do I pass request parameters using the REST protocol?

If using HTTP POST, include the request parameters in the HTTP body using JSON encoding. With HTTP GET, ensure the request parameters are included in the URI as query parameters.

What happens when I pass merchant-defined fields to the API?

Merchant-defined fields are not supported in this version of the Mastercard Payment GatewayAPI.

What happens when I re-submit a transaction?

The re-submitted identical transaction will return the same response as the first. All operations in this version of the Mastercard Payment GatewayAPI are idempotent; that is, the effects of repeated identical requests are the same as that for a single request. Therefore you can be assured that the transaction will not be repeated with your or the payer's bank.

Do I need to create a new order if the initial transaction for the order fails?

From API v15 onwards, if the initial transaction for an order fails, you can submit a new initial transaction (with a new transaction ID) for this order without having to create a new order.

What happens if I provide card details in a subsequent Capture or a Refund transaction?

From API v15 onwards, if you want to perform a subsequent Capture or a Refund transaction against a successful initial transaction, you must NOT provide card details in your request. If you provide card details when the order already has a successful initial transaction, then the Mastercard Payment Gateway rejects the request.

What should I do if I do not receive a response?

When you do not receive a response, it is recommended that you wait for 60 seconds and attempt to resubmit the identical request. The bank transaction will not be repeated again and rest assured no duplicate funds will be transferred. You will receive the same response as you would have received for the first request.

How do I know if a transaction has been approved?

All approved transactions are represented with a Transaction Response Code of APPROVED from the Mastercard Payment Gateway. Any other code represents a declined or failed transaction.

What happens if the payer double submits (double clicks) the Payment Details Form?

The re-submitted identical transaction will return the same response as the first as all operations in the Mastercard Payment Gateway are idempotent (the side-effects of N > 0 identical requests is the same as for a single request). So, you can be assured that the transaction will not be repeated with your or the payer's bank.

Best Practices and Tips

Validate the SSL Certificate of the Mastercard Payment Gateway

It is highly recommended that you validate the SSL certificate of the Mastercard Payment Gateway whenever you connect to the Mastercard Payment Gateway. the Mastercard Payment Gateway SSL certificate is issued by an industry standard Certificate Authority such as Verisign or Thawte whose root certificate should already be available in your web environment.

Please consult a web developer if you are not familiar with validating SSL certificates or exporting certificates from web sites. Always ensure the server is a trusted source.