DIRECT GATEWAY API
Documentation
Getting Started with Sathapana Direct Gateway
Guidelines to implement the Sathapana Direct Gateway Solution.
Prerequisites:
- Ensure that your merchant profile is enabled for API
- For more details and sample code, please refer to this link Direct Gateway Integration Guide (mastercard.com)
The table below enables you to assess the logistics involved when integrating with API. Both the protocols, REST and NVP, offer the same functionality. However, there might be certain factors to consider before you make your decision.
Step 1: Access the gateway
Try and access the following URL through a web browser:
If the gateway is able to process requests, i.e., if successful, the "information" file displays {"status":"OPERATING"} in the JSON format for the REST protocol. NVP displays status=OPERATING.
Step 2: Knowing Your Input Fields
Before performing a test transaction, you must be prepared with the values for the fields that require your input.
**Note: Do NOT ever use hidden form fields (<input type="hidden" />) to pass information relevant to processing a transaction, especially for fields like amount, Merchant ID and API Password. Most importantly, you should NEVER expose the following fields to a payer (including using a hidden field):
- Merchant ID
- API Password
These values should be stored securely by your application/website in a configuration file or database. If a fraudulent user were to gain access to this data, your account would be susceptible to a potential attack.
Step 3: Create the Transaction Request
Creating the body of the request is a critical step in the merchant integration. The form fields from the payer-facing form together with your configuration fields are submitted to the MasterCard Payment Gateway API URL using HTTPS POST/PUT/GET depending on the chosen protocol (REST-JSON/NVP) and the transaction operation.
The below code snippets complete two critical functions to result in a correctly formatted transaction request body:
- Ensure no empty or blank fields are added to the transaction request body
- Format the data to the requirements of each protocol (Name-value-pair for NVP or JSON for REST)
Step 4: Send the Transaction Request
There are many components to making sure the transaction request body is sent securely to the Payment Gateway. This section goes through the essential concepts and functions you may need to use in your integration. For more details and sample code snippets, please refer to Send Transaction Request (mastercard.com)
- Authentication Data: The MasterCard Payment GatewayAPI requires every transaction request to be authenticated successfully. The below snippet covers how to provide authentication data (Merchant ID and/or API Password) with each transaction.
- HTTP Headers: HTTP Headers provide metadata information about the transaction request being sent to the the MasterCard Payment Gateway. The Content-Length and Content-Type headers are critical because they tell the web server how many bytes of data to expect, and what kind, identified by a MIME type. The character encoding of your request must include only ISO-8859-1, Latin1, or UTF-8 formats.
- HTTP Method (POST vs PUT vs GET): Depending on your protocol and integration options chosen, you may need to use a specific HTTP method for each transaction. All the basic operations performed through the MasterCard Payment Gateway API use HTTP method PUT with the REST protocol (except Retrieve and Check Gateway operations); and HTTP method POST with the NVP protocol.
- Destination URL for a Transaction Request: The URL used to send your transaction request can change for every transaction request:
- With NVP, you will always use the same URL for all transaction operations. In the below snippet, the function calculates the URL from configuration and appends the version of the API being used.
- With REST, the URL will vary for every transaction operation. In the below snippet, the function calculates the URL from config, sets the version and Merchant resource values and then appends a custom list of resources and their identifiers. These custom components could represent the order and transaction resources.
- Set the URL to Send Transaction: We need to create the web request and set destination URL to send a transaction to the gateway.
- Verify the MasterCard Payment Gateway's SSL Certificate: In order to prevent malicious attacks as well as other potential security issues, it is critical that you validate the SSL certificate of the MasterCard Payment Gateway when you send the transaction request.
- Configure a Proxy Server: In some network environments, it may be necessary to send the transaction request via a proxy server. This is optional and you should consult your network administrator or web hosting provider for information on whether this is relevant to your integration.
- Send Transaction to the MasterCard Payment Gateway: As a last step, you must send your correctly formatted transaction request to the MasterCard Payment Gateway and wait for a response.
Step 5: Process the Transaction Response
Once a transaction request has been sent to the MasterCard Payment Gateway, you will 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 will need to decode and parse the transaction response. For more details and sample code snippets, please refer to Process Transaction Response (mastercard.com)
- How to Decode the Response: When you receive the response to your transaction, it will be encoded or formatted in the same format as the transaction request. To make this data more accessible, you may need to decode this data and store it in an array or similar.
- How to Parse the Response: Once you have decoded the transaction response and have it stored in an easily accessible object, you can then parse the response to retrieve or store any of the fields in the transaction response. Please note that for all API operations, there will always be a "result" field in the response. This field indicates the overall result/status of your transaction. You can use this field to determine different processing options within your application, for example if it is a SUCCESS, then you can record the transaction as being processed successfully. If it returns a FAILURE, you may want to look further at the transaction response and determine if the payer should retry the transaction or execute another process within your application.
- Using the Transaction Response: You should spend some time examining the transaction response parameters for each relevant operation in the API Reference. All of these fields provide valuable information, and many of which you may wish to store locally for accounting, reconciliation, and traceability reason. You may also wish to display a receipt number or similar to the payer. For more complex integrations, it may also be useful for you to look further into specific response codes to gather all aspects of the transaction. It is also a good practice to validate whether the data you supplied for the transaction is the same data used to process the transaction. For example, you should check that amount returned in the transaction response matches the value you sent in the transaction request.
Step 6: Test and Go Live
Please refer to this link for more details and the sample data for testing Test and Go Live (mastercard.com)