Integration Guide

Step 1: Check the gateway connectivity

Before you send any requests, check your connectivity to the gateway. To check, access the following URL through a web browser: https://evopaymentsmexico.gateway.mastercard.com/api/rest/version/1/information. If the connection attempt is successful and the gateway processes requests, then the browser page displays {"status":"OPERATING"}.

Step 2: Set up your authentication method

The gateway supports two methods of authentication, SSL Secure Sockets Layer (SSL) certificates and passwords.

Select the method that best serves your business model and implement it.
If you use SSL certificates as your authentication method, ensure to validate the SSL certificate path of gateway whenever you connect to the gateway. Contact a web developer if you are unfamiliar with how to validate or export the SSL certificates from websites. Ensure the server is a trusted source.

Step 3: Create the transaction request

Creating the body of the request is a critical step in your integration. The request body fields gathered from the payer-facing form and generated within your system are submitted to the API URL in REST JSON format. Depending on the transaction operation, one of the following HTTP methods is used in URL:

POST is used when you want the system to create a new collection.
PUT is used when you want to add or modify a member of a collection.
GET is used to retrieve operations.

The payer-facing form must only expose the fields that require input from the payer. Values for fields such as Order ID, Transaction ID, Version, and Merchant ID must be calculated within your code.

Format request body data from forms

Regardless of the language selected in the code snippet; it is important that your integration formats the transaction request data correctly. In many languages, it is common to receive the form data that a payer has entered, as an array.

In most cases, you can then use an array to store the field names and values for each field you intend to pass to the gateway and format it as demonstrated in the following snippet. This code snippet completes two critical functions to result in a correctly formatted transaction request body:

Ensures no empty fields are added to the transaction request body.
Formats the data according to the JSON protocol.

How to Convert Form Data to

(, ) Change

This code snippet shows how to convert form data to .

    
         Select Protocol and Language to view Code Snippet.

From: Sample Code Download

Step 4: Send the transaction request

Follow these steps to ensure that the transaction request body is sent securely to the payment gateway:

Set authentication data

The API requires each transaction request to be authenticated successfully. If you are using the API password as your authentication method, the following snippet covers how to provide the authentication data, such as merchant ID or API password or both, as a header in each transaction request.

Select Protocol and Language to view Code Snippet.

From: Sample Code Download

Do not include the authentication header if you are using the SSL certificate authentication.

Set HTTP headers

HTTP headers provide metadata information about the transaction request sent to the gateway. In addition to any authentication headers that are covered in the previous sections, the following snippet demonstrates how to set the mandatory HTTP headers for each transaction request.

The Content-Length and Content-Type headers are critical as they indicate the web server about the number and type of data bytes, identified by a MIME type.

The character encoding of your request must include either ISO-8859-1 or UTF-8 format. The gateway rejects any characters that cannot be represented in one of the supported formats. If not specified, the gateway defaults the encoding to ISO-8859-1. Following is an example of the Content-Type header.

Example Content-Type header

"Content-Type: application/json; charset=UTF-8"

To set the header, use the following code.

Select Protocol and Language to view Code Snippet.

From: Sample Code Download

Although UTF-8 is a supported character format, any field which is sent to a credit card processor is restricted to ISO-8859-1 characters. This is because downstream financial systems are not able to support all UTF-8 characters.

Use specific HTTP method

Using a specific HTTP method such as POST, PUT, or GET for each transaction is important. All the basic operations performed through the API, use the HTTP, POST, or PUT method, except for the CHECK GATEWAY and various retrieval operations:

HTTP PUT method updates the addressed member of the collection; or if it does not exist, creates a new member. For example, consider a request where the Request URI value is: http://example.com/version/v1/merchant/m1/order/o1/transaction/t1

In the URI, t1 is a member of the collection resource o1. If t1 exists, the request modifies the resource t1, and if not, it creates a new member t1.

HTTP GET method retrieves a representation of the addressed member of the collection. For example, consider a request where the Request URI value is: http://example.com/version/v1/merchant/m1/order/o1/transaction/t1

The request retrieves t1 member of the collection resource o1.

HTTP POST method creates a new collection. In the gateway APIs, it is mainly used for operations that create a new set of data, like the CREATE SESSION or PAYMENT OPTIONS INQUIRY operation.

The following code snippet shows how to use the HTTP POST method.

Select Protocol and Language to view Code Snippet.

From: Sample Code Download

The following code snippet shows how to use the HTTP PUT method.
Select Protocol and Language to view Code Snippet.

From: Sample Code Download

Define the destination URL

The URL used for sending transaction request varies for each transaction operation. In the following snippet, the function calculates the URL from your configuration, sets the version and merchant resource values, and finally appends a custom list of resources and their identifiers.

These custom components represent the order and transaction resources. For more information about the URL format for each operation, see the individual operations within the API Reference.

Select Protocol and Language to view Code Snippet.

From: Sample Code Download

Set the URL to send the transaction

The following code snippet shows how to set the URL to send a transaction.

Select Protocol and Language to view Code Snippet.

From: Sample Code Download

Verify the SSL certificate of a gateway

If you are using the SSL certificate authentication method, validate the SSL certificate of the gateway. Validating SSL certificate when you send the transaction request prevents malicious attacks and other potential security issues. The following code snippet shows how to verify the SSL certificate.
Select Protocol and Language to view Code Snippet.

From: Sample Code Download

Configure a proxy server

In some network environments, it can be necessary to send the transaction request through a proxy server. Contact your network administrator or web hosting provider for information about whether a proxy server is required for your integration. The following code snippet shows how to set a proxy and its authentication.

Select Protocol and Language to view Code Snippet.

From: Sample Code Download

Send the transaction to the gateway

Send the correct formatted transaction request to the gateway and wait for a response. The following code snippet shows how to send a transaction to the gateway.

Select Protocol and Language to view Code Snippet.

From: Sample Code Download

On This Page