# Make a Server API Request
source: https://developer.mastercard.com/mastercard-gateway/documentation/tutorials-and-guides/server-api-request/index.md
## Overview {#overview}
This is the general process of creating an API request and sending it to the Mastercard Gateway.
It helps to understand how to:
* Prepare and send a Pay transaction using tokenized card details.
* Authenticate your request using your API password.
* Format and send your request using cURL.
## Prerequisites {#prerequisites}
Make sure that you meet the following prerequisites, before making an API request:
* You have a merchant account with the privileges for using the operation and payment method you want to use in the request.
* You have an API password for authentication (unless you are using SSL certificate authentication). For details, see Authentication Options.
* You have gathered the mandatory payer and order details you need to provide in the request. You can get many details directly from your system, but some details are needed directly from the payer in cardholder-initiated transactions. Depending on your setup, you can get those details, for example, by using input fields in your app or web site to capture the data the payer enters. Note: For a collection of example requests covering the common transaction operation requests with their mandatory request fields, download the [Postman collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api).
## Step 1. Check the gateway connectivity {#step-1-check-the-gateway-connectivity}
Before you send any requests, check your connectivity to the gateway.
Try to access the following URL through a web browser:
https://mtf.gateway.mastercard.com/api/rest/version/100/information
If the connection attempt is successful and the gateway is able to process requests, the browser page displays: `{"status":"OPERATING"}`
## Step 2. Create the request {#step-2-create-the-request}
To create the request, you must define:
##### 1. HTTP method {#1-http-method}
Use the appropriate HTTP method based on the type of operation.
###### PUT {#put}
Use PUT to create or update a specific resource. If the resource already exists, it updates and if not, it creates a resource.
For example:
{{host}}/version/100/merchant/m1/order/o1/transaction/t1
This updates or creates transaction **t1** under order **o1**.
###### GET {#get}
Use GET to retrieve a specific resource.
For example:
{{host}}/version/100/merchant/m1/order/o1/transaction/t1
This fetches transaction **t1** from order **o1**.
###### POST {#post}
Use POST to create a new resource within a collection. Commonly used for operations like creating sessions or initiating payment inquiries.
For example:
{{host}}/version/100/merchant/m1/order/o1/transaction
This creates a new transaction under order **o1**.
###### HTTP method example {#http-method-example}
```sh
curl --location --request PUT
```
##### 2. URL {#2-url}
Use the URL to send your transaction request varies for every transaction operation. It often includes path parameters that define crucial identifiers, such as the merchant ID, order ID, and transaction ID.
Note: For the correct host address to use in the URL, contact your Payment Server Provider (PSP).
###### URL method example {#url-method-example}
```sh
curl --location --request PUT
'{{host}}//merchant//order//transaction/' \
```
##### 3. HTTP headers {#3-http-headers}
HTTP headers provide metadata about the transaction request sent to the gateway. Every request must include the following mandatory headers.
###### Content-Length and Content-Type {#content-length-and-content-type}
These headers define the size and format (MIME type) of the request body. Supported character encodings are **ISO-8859-1** and **UTF-8** . If not specified, the gateway defaults to **ISO-8859-1**.
Note: Fields sent to credit card processors must use **ISO-8859-1** . Some downstream financial systems do not support all **UTF-8** characters.
###### Authorization {#authorization}
If you're using API password authentication, include the authorization header with your API credentials in every request. Do not include this header if you're using SSL certificate-based authentication.
###### HTTP headers example {#http-headers-example}
```sh
curl --location --request PUT
'{{host}}//merchant//order//transaction/>transaction_ID<' \
--header 'Content-Type: application/json' \
--header 'Content-Length: 175' \
--header 'Authorization: Basic user_ID<:">' \
```
##### 4. Request body {#4-request-body}
Provide the request body in JSON format. Include all mandatory fields, and optionally add any additional fields that may enhance processing. The optional fields can improve transaction handling across financial systems by supporting risk analysis and authentication.
###### Request body example {#request-body-example}
```sh
curl --location --request PUT '{{host}}//merchant//order//transaction/' \
--header 'Content-Type: application/json' \
--header 'Content-Length: 175' \
--header 'Authorization: Basic :">' \
--data '{
"apiOperation": "PAY",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "9887513336741609",
"provided": {
"card": {
"securityCode": "123"
}
}
}
}
'
```
## Step 3. Send the request {#step-3-send-the-request}
After formatting your transaction request, send it to the gateway and wait for a response.
###### Verify the gateway's SSL certificate {#verify-the-gateways-ssl-certificate}
If you're using SSL certificate authentication, you must validate the gateway's SSL certificate to protect against malicious attacks and ensure secure communication.
###### Configure a proxy server {#configure-a-proxy-server}
In some network environments, you may need to route the request through a proxy server.
Consult your network administrator or hosting provider to determine if this is necessary.
## Step 4. Interpret the response {#step-4-interpret-the-response}
After sending a transaction request, the gateway typically returns a response quickly. To determine the outcome and extract useful data, you must decode and parse the response.
###### Understand the response format {#understand-the-response-format}
The response is returned in the same format as the request, typically JSON. Parse the response to access the fields you need.
###### Use the result field {#use-the-result-field}
Every response includes a result field that indicates the transaction status:
* Success -- The transaction was processed successfully.
* Failure -- The transaction failed. Check additional fields to determine if the payer should retry or if your application should take further action.
###### Validate returned data {#validate-returned-data}
Verify that the response data matches your request---for example, confirm that the returned amount equals the amount you sent.
###### Store relevant fields {#store-relevant-fields}
Review the API Reference to understand which fields are returned for each operation. Store important fields locally for:
* Accounting and reconciliation
* Traceability
* Displaying receipts or confirmation numbers
###### Response body example {#response-body-example}
```sh
{
"authorizationResponse": {
"commercialCard": "888",
"commercialCardIndicator": "3",
"financialNetworkCode": "777",
"posData": "1025100006600",
"posEntryMode": "102",
"processingCode": "003000",
"responseCode": "00",
"stan": "182118",
"transactionIdentifier": "123456789"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"chargeback": {
"amount": 0,
"currency": "EUR"
},
"creationTime": "2023-11-03T13:49:07.464Z",
"currency": "EUR",
"fundingStatus": "IN_PROGRESS",
"id": "123455",
"lastUpdatedTime": "2023-11-03T13:49:07.500Z",
"merchantAmount": 100.00,
"merchantCategoryCode": "1111",
"merchantCurrency": "EUR",
"status": "CAPTURED",
"totalAuthorizedAmount": 100.00,
"totalCapturedAmount": 100.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"number": "512345xxxxxx0008",
"scheme": "MASTERCARD"
}
},
"token": "9887513336741609",
"type": "CARD"
},
"timeOfLastUpdate": "2023-11-03T13:49:07.500Z",
"timeOfRecord": "2023-11-03T13:49:07.181Z",
"transaction": {
"acquirer": {
"batch": 20231103,
"date": "1103",
"id": "CISTEST_S2I",
"merchantId": "342342344",
"settlementDate": "2023-11-03",
"timeZone": "+1100",
"transactionId": "123456789"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"authorizationCode": "182118",
"currency": "EUR",
"funding": {
"status": "IN_PROGRESS"
},
"id": "2",
"receipt": "330713182118",
"source": "INTERNET",
"stan": "182118",
"terminal": "2323323",
"type": "PAYMENT"
},
"version": "100"
}
```
## FAQs {#faqs}
### Are the API field names case-sensitive? {#are-the-api-field-names-case-sensitive}
Yes, the API field names for all operations are **case-sensitive**.
*** ** * ** ***
### How do I pass request details using the REST protocol? {#how-do-i-pass-request-details-using-the-rest-protocol}
* For **HTTP POST** or **PUT** , include the request fields in the HTTP body using **JSON encoding**.
* For **HTTP GET** , include any request details in the URI as **query parameters**.
*** ** * ** ***
### What happens when I pass merchant-defined fields to the API? {#what-happens-when-i-pass-merchant-defined-fields-to-the-api}
Merchant-defined fields are **not supported** , except within the `order.custom` object.
*** ** * ** ***
### How do I know if a transaction has been approved? {#how-do-i-know-if-a-transaction-has-been-approved}
* Approved transactions have a **transaction response code** value of `APPROVED` from the gateway.
* Check the `response.gatewayCode` field in your transaction response.
* Any other code value represents a **declined or failed transaction** . For more details, see **Transaction Errors**.
*** ** * ** ***
### What should I do if I do not receive a response? {#what-should-i-do-if-i-do-not-receive-a-response}
* Wait **60 seconds** , then attempt to **resubmit an identical request**.
* The bank transaction is **not repeated**, and no duplicate funds are transferred.
* You will receive the same response as if the first request had not timed out.
*** ** * ** ***
### Can I use complex query conditions for HTTP requests to the REST APIs? {#can-i-use-complex-query-conditions-for-http-requests-to-the-rest-apis}
No, the Mastercard Gateway APIs do **not support combining conditions using AND or OR operators**.
* Break your query into **separate requests**, each handling one condition.
* Manage the results separately and combine them later without issues.
*** ** * ** ***