Send a Request
Follow these steps to send a request to the Direct Payment for a transaction operation:
For more information about:
- Sending API requests to the Direct Payment and for FAQs about handling request details, see Making a Server API Request.
- Managing error situations with API requests, see API Error Handling.
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://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"}.
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.
- For general information about each method, see Authentication Options.
- For instructions on how to implement your selected method, see Setting up API Credentials.
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.
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
(, ) ChangeSelect 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
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.
"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
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