Making a Server API Request
This topic describes the general process of creating an API request and sending it to the Mastercard Gateway.
- Apply to a PAY transaction operation using the credit card payment method with tokenized card details. For more information about all available transactions and payment methods, see transactions, payment methods, and list of REST server APIs.
- Assume that you are sending the request from your backend server using your API password as your authentication method. If you need to send the request from the frontend client side, you must use session authentication in your request to avoid having to use your API password at the frontend. For more information, see Session Authentication.
- Show basic request element examples using cURL. To see how to build the request in your code using Java, C#, PHP, or SHELL code snippets, see sending a request and interpreting a response for the Direct Payment integration.
For more information related to API requests in general, see:
Prerequisites
Before making an API request, check that you meet the following prerequisites:
- You have a merchant account with the privileges for using the operation and payment method that you want to use in the request.
- You have an API password for authentication unless you are using SSL certificate authentication. For more information about various authentication types, see Authentication Options.
- You have gathered the mandatory payer and order details that 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 that the payer enters.
For a collection of example requests covering the common transaction operation requests with their mandatory request fields, download the Postman Collection.
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://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/1/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
In the request, you must define:
- HTTP method
- URL
- HTTP headers
- Request body (payload)
HTTP method (POST/PUT/GET)
You need to use a specific HTTP method for each transaction:
- HTTP PUT method is typically used when the URL contains a member of the collection. It updates the addressed member, or if a member does not exist, creates a new member. For example, consider a request where the Request URI value is:
https://example.com/version/v1/merchant/m1/order/o1/transaction/t1.
In the URI,
t1is a member of the collection resourceo1. Ift1exists, the request modifies the resourcet1, and if not, it creates a new membert1. - HTTP GET method retrieves a representation of the addressed member of the collection. For example, consider a request where the Request URI value is:
https://example.com/version/v1/merchant/m1/order/o1/transaction/t1.
The request retrieves t1 member of the collection resource
o1. - HTTP POST method is typically used when you want the system to create a new collection.
In the gateway APIs, it is mainly used for operations that create a new set of data, like the
CREATE SESSIONorPAYMENT OPTIONS INQUIRYoperation.
To determine the correct method for your operation, check the API Reference.
curl --location --request PUT
URL
The URL used 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.
For more information about the order and transaction identifiers and how to use them, see Identifiers. To determine the correct URL and path parameters for your operation, check the API Reference.
curl --location --request PUT 'https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID>' \
HTTP headers
HTTP headers provide metadata information about the transaction request that is sent to the gateway. Every transaction request needs the following mandatory HTTP headers:
Content-Length and Content-TypeThe preceding headers are critical because they notify the web server how many bytes of data to expect in what format, identified by a MIME type. The character encoding of your request must include ISO-8859-1 or UTF-8 format, as 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.
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 due to downstream financial systems not being able to support all UTF-8 characters.AuthorizationIf you are using the API password as your authentication method, you must add the
Authorizationheader with your API credentials in every request. Do not include the header if you are using the SSL certificate authentication.
To determine the correct method for your operation, see API Reference.
curl --location --request PUT 'https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/order/<order_ID>/transaction/>transaction_ID<' \
--header 'Content-Type: application/json' \
--header 'Content-Length: 175' \
--header 'Authorization: Basic <base64-encoded string of “merchant.>user_ID<:<password>”>' \
Request body
Provide the request body fields in JSON format. In addition to the mandatory fields, you can include as many optional fields as you like. Optional fields can often make the payment processing smoother in the various financial systems the transaction passes through, as they can help in risk analysis and authentication. For more information, see Payment Enhancements.
curl --location --request PUT 'https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID>' \
--header 'Content-Type: application/json' \
--header 'Content-Length: 175' \
--header 'Authorization: Basic <base64-encoded string of “merchant.<user_ID>:<password>”>' \
--data '{
"apiOperation": "PAY",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "9887513336741609",
"provided": {
"card": {
"securityCode": "123"
}
}
}
}
Step 3: Send the request
Send your correctly formatted transaction request to the gateway and wait for a response.
Gateway's SSL certificate verification
If you are using the SSL certificate authentication method, you must validate the SSL certificate of the gateway when you send the transaction request to prevent malicious attacks and other potential security issues. For a code example about how to do this, see sending a request for Direct Payment.
Proxy server configuration
In some network environments, it can be necessary to send the transaction request through a proxy server. Consult your network administrator or web hosting provider for information about whether this is required for your integration. For a code example about how to do this, see sending a request for Direct Payment.
Step 4: Interpret the response
Once a transaction request is sent to the gateway, you generally receive a response within a very short period. To determine the success of your transaction, as well as obtain other important data from the transaction response, you need to decode and parse the transaction response.
Spend some time examining the transaction response fields for each relevant operation in the API Reference. Ignore unknown fields or fields that you do not need. All the fields provide valuable information, and you probably want to store some of them locally for accounting, reconciliation, and traceability reasons. You can also use them to display a receipt number or similar to the payer. The more complex your integration is, the more useful it can be to study specific response codes to identify all aspects of the transaction status.
When you receive the response to your transaction, it is encoded or formatted in the same format as the transaction request. To make this data more accessible, you can decode and store it in an array or similar, and parse the data to retrieve any of the fields that you need.
- If the transaction result value is
SUCCESS, you can record it as being processed successfully. - If the result is
FAILURE, you can look further at the transaction response to determine whether the payer must retry the transaction, or whether you must execute another process within your application.
Response example
{
"authorizationResponse": {
"commercialCard": "888",
"commercialCardIndicator": "3",
"financialNetworkCode": "777",
"posData": "1025100006600",
"posEntryMode": "102",
"processingCode": "003000",
"responseCode": "00",
"stan": "182118",
"transactionIdentifier": "123456789"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "<merchant_ID>",
"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": "75"
}
FAQs
How do I know what the latest version of the API is?
The latest API version is shown in the page title.
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?
If you are using the HTTP POST or PUT, include the request fields in the HTTP body using JSON encoding. With HTTP GET, include any request details in the URI as query parameters.
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?
All approved transactions are represented with a transaction response code value of APPROVED from the gateway. See the response.gatewayCode field in your transaction response. Any other code value represents a declined or failed transaction. For more information, see Transaction Errors.
What should I do if I do not receive a response?
When you do not receive a response, wait for 60 seconds, and attempt to resubmit an identical request. The bank transaction is not repeated, and no duplicate funds are transferred. You would get the same response that you would have received had the first request not timed out.