Integration Types
Other Features
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
Follow these steps to send a request to the Direct Payment for a transaction operation:
Before you send any requests, check your connectivity to the gateway. To check, access the following URL through a web browser: https://na.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"}.
The gateway supports two methods of authentication, SSL Secure Sockets Layer (SSL) certificates and passwords.
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:
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:
Select Protocol and Language to view Code Snippet.
From: Sample Code Download
Follow these steps to ensure that the transaction request body is sent securely to the payment gateway:
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
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.
"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
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.
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
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
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
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
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 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