Making a Server API Request

This topic describes the general process of creating an API request and sending it to the Mastercard Gateway .

The instructions in this topic:
  • Apply to a PAY transaction operation using the credit card payment method with tokenized card details. For details 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 Java, C#, PHP, and SHELL code snippets on how to build the request in your code, see Sending a request and interpreting a response for the Direct Payment integration.

For more information related to API requests in general, see:

Prerequisites Copied to Clipboard

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 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.

    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://mepspay.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, 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:

    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 SESSION or PAYMENT OPTIONS INQUIRY operation.

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 on 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.

For the correct host address to use in the URL, contact your Payment Server Provider (PSP).

        curl --location --request PUT 'https://mepspay.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 sent to the gateway. Every transaction request needs the following mandatory HTTP headers:

  • Content-Length and Content-Type

    The above headers are critical because they tell 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 only ISO-8859-1 or UTF-8 formats, 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.
  • Authorization

    If you are using the API password as your authentication method, you must add the Authorization header 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, check the API Reference.


        curl --location --request PUT 'https://mepspay.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://mepspay.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

As the last request-related action, send your correctly formatted transaction request to the gateway and wait for a response.

Verifying the gateway's SSL Certificate

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 on how to do this, see Sending a request for Direct Payment.

Configuring a proxy server

In some network environments, it can be necessary to send the transaction request via a proxy server. Consult your network administrator or web hosting provider for information on whether this is required for your integration. For a code example on how to do this, see Sending a request for Direct Payment .

Step 4: Interpret the response

Once a transaction request has been 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.

It is a good practice to validate whether the data you supplied for the transaction is the same as the data used to process the transaction. For example, check that the amount returned in the transaction response matches the value you sent in the request.

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 you need.

All API operations contain a result field in the response. This field indicates the overall result and status of your transaction. Use it to determine different processing options within your application. For example:
  • 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 Copied to Clipboard

How do I know what the latest version of the API is?

Go to https://mepspay.gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/latest/api.html.

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 using 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.

Can I use complex query conditions for HTTP requests to the REST APIs?

The Mastercard Gateway APIs do not support combining conditions using AND or OR operators. Break your query into separate requests, each handling one condition. You can manage the results separately and combine them later without any issues.