Send a Request
Follow these steps to send a request to the <<directPayment>> for a transaction operation:
For more information about:
- Sending API requests to the <<directPayment>> 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 sending any requests, confirm that your system can connect to the gateway. To do this:
- Open a web browser.
- Go to this URL https://qnbalahli.gateway.mastercard.com/api/rest/version/100/information.
- If the connection is successful and the gateway is operating, the browser page will display: {"status":"OPERATING"}.
If you do not see this message, there may be a connectivity issue preventing your requests from reaching the gateway.
Step 2: Setting up authentication for gateway access
To connect securely to the gateway, you need to set up an authentication method. The gateway supports two options:
- Secure Sockets Layer (SSL) Certificates – Uses digital certificates for authentication.
- Passwords – Requires a password-based login.
Choose the option that best fits your business needs and follow the setup instructions:
- For a general overview, see Authentication Options.
- For step-by-step setup, see Setting up API Credentials.
If you use SSL certificates, always verify the certificate path before connecting to the gateway. If you are unsure how to validate or export certificates, ask a web developer for help. Make sure your connection is secure and the server is trusted.
Step 3: Creating a transaction request
When integrating with the payment system, you need to build a request body that includes relevant transaction details. This data comes from:
- The payer-facing form (where customers enter payment details).
- Your system-generated fields (such as transaction identifiers).
The request must be sent to the API URL in REST JSON format. Depending on the type of transaction, use one of the following HTTP methods:
- POST – Creates a new collection.
- PUT – Adds or updates a specific item in a collection.
- GET – Retrieves information.
The payer-facing form should only display fields that need direct input from the payer (such as card details). Other values like Order ID, Transaction ID, Version, and Merchant ID should be calculated within your code before sending the request.
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
(, ) ChangeStep 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.
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"
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.
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.
Set the URL to send the transaction
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.
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.
Send the transaction to the gateway
Send the correct formatted transaction request to the gateway and wait for a response.