Overview

Introduction

REST API is one of ways to integrate with the platform and provides full opportunities for interaction with the payment platform. REST API supports the ability to perform purchases, recurring payments, refunds and payouts. gateway allows to process card payments of the following types: Maestro, Mastercard and Visa, American Express (AMEX), JCB , CUP etc. and other alternative payments.

For issuing of payments by using REST APIs , you need to develop your own payment interface, with full UI control. For payment processing by using payment cards, your payment interface needs to be a PCI-compliant.

The merchant’s web service sends a request to the API end points when performing a payment. Our payment gateway receives the request, and server processes that request and redirects it to the third parties participating payment and responds with a callback containing the final payment result.

The sections about payment gateway cover the following:

Payment models and operations — This section contains the overview of payment types and payment-related requests and operations, processing models and possible statuses of payment processing by using Payment Page.
Interaction concepts — How to integrate by using Payment Gateway, technical aspects on interaction between the web service and the payment checkout page, including interaction models and the formats of request, response and callback.

Payment Model & Operations

The payment platform is used to process payment, acting as an intermediary between the merchant and the customer. Payment created in the payment platform is a set of tasks to transfer funds between them. It can be a transfer of funds from the customer to the merchant (purchase), or from the merchant to the customer (payout). For Sales, the merchant can either have Direct Capture, or can have two step debit transaction where the Transaction Amount is first put on Hold by the issuing bank, and then captured later by the merchant.

In the payment platform there are following payment types:

Purchase - One-time transfer of funds from customer to merchant performed in one step or two steps as follows:
- Synchronous - In a synchronous workflow the payment data are directly sent to the server. That means that the transaction can be processed straight away.
- Asynchronous - In an asynchronous workflow the account holder has to verify the payment. Once the account holder verifies the account he/she is redirected back to the merchantRedirectUrl. The merchant than can query the status of payment.
- 3d - In a 3D workflow the account holder is redirected to the ACS page with provided parameters and has to verify the payment. Once the account holder verifies the payment he/she is redirected back to the merchantRedirectUrl. The merchant then can query the status of payment.
Recurring - Setting up recurring payments gives you the option of selling products or services automatically. It optimizes the checkout experience and makes it much easier to predict the cash flow. In short, recurring payments are repeated ones. It’s when you are charged automatically for items or services that are delivered to you on a regular basis. It could be for any period of time depending on the business model. The process needs to be initiated by an initial sale. In order to use recurring solution, the connecting bank must support Recurring payments.
There are two possible workflows for recurring:
Initial payment:
- Initial recurring payment with transaction
- Initial recurring payment using the stored payment
Repeat payment:
- Repeat recurring payment with registrationId
- Repeat recurring payment with paymentId
Tokenization - Tokenization makes your transactions easier and is completely supported by the payment platform. Once you have created a token, you don’t have to enter all the payment data every time, because the data will be stored with the tokenization. That makes it possible to use the payment data later. The token can be used for recurring transactions.
There are two ways of registering the payment data.
- Store the data during a payment
- Store the data as stand-alone
Payout - Payout is transfer of funds from merchant to customer.
Invoice - Merchant can generate an Invoice for the customers and inform them regarding the generated invoice, for their orders through email. Customers can pay for their orders using the Payment-link provided on the emails.
Backoffices - A merchant can perform following BackOffice operations using our REST API.

Payment	Operation
Purhcase	Debit: A transaction combining both, the Auth and Capture transactions. It instructs the gateway to perform both actions one after the other, query the bank for authorization and – upon approval – immediately capture the relevant transaction.
	Preauthorization: A request made by the merchant to the gateway to authorize the availability of a required amount of funds for a specific credit card. An authorization verifies that a card is valid and has sufficient funds to complete this transaction. If approved, the authorized amount is held until it is completed, or an expiry time is reached.
	Capture: Request to capture a previously-authorized transaction hence transferring the funds from customer’s bank account to merchant’s bank account. This transaction is always preceded by an auth transaction.
	Reversal/Cancel: Requests to cancel previously authorized transaction. It returns the specified amount to the cardholder’s account. The amount being requested for reverse is less than or equal to the original authorized amount.
	Refund: Request to refund a previously settled transaction. However it is not possible to refund the same transaction more than once. It returns the specified amount (posts a credit) to the cardholder’s account. The amount being requested for refund is less than or equal to the original captured amount.
Recurring	Initial: Initial operation is the parent transaction which returns a transaction id that will be used in the subsequent transactions.
Recurring	Repeated: REPEATED transactions are the child transactions made with INITIAL transaction's tracking ID.
Payout	Payout: Payout enables merchant to transfer money back into given cardholder's account.

Integration steps

To obtain access to the payment platform by using API, you need to complete the following tasks:

Check the following organizational interaction issues with :
- Your company has to obtain Merchant ID and Secret Key from . You will be provided with credentials if your company is connecting to for the first time.
- You also need to have a ready copy of your PCI DSS compliance certificate or, if your company is not PCI DSS-compliant, complete Self-Assessment Questionnaire as below:
  - Completing Self Assessment
  - SAQ Document
- Our technical support can assist in testing the integration API. The support will assist in setting up the test environment as well as going on live environment. You can coordinate the testing procedures and all the other information
Merchant has to update the code for their web service to implement the integration with the Payment Gateway Environment through our APIs.
Test the environment and put the updated web service code in production mode with our technical support person.

For further assist regarding API integration you can contact on

Interaction models

The platform and merchant's web service interact by exchanging request and reply messages in the HTTP format: the web service issues requests and the payment platform responds to those requests.

The interaction model supports two interaction models: Viz. Synchronous and Asynchronous. If the payment platform is able to respond to request without resorting / depending to any third parties such as customer or external payment system, it uses the synchronous model; otherwise the payment platform uses the asynchronous model.

In an asynchronous workflow the account holder has to verify the payment. Once the account holder verifies the account he/she is redirected back to the merchant’s redirect URL. The merchant than can query the status of payment.

Synchronous Flow

When it can generate the response by using only its own data and resources, Synchronous flow can be integrated. For example: To get current status of payment, Synchronous interaction is performed in a single HTTP session and allows you to send only one response.

Asynchronous Flow

The Asynchronous Flow is used at that time when payment gateway needs to communicate with third parties. For example it requires input from customer when it processes the payment. Payment method send the acknowledgement that initial request is accepted successfully and validated and callback with appropriate message is sent.

In some case where a redirect URL is returned in the response of the initial request, the customer has to be redirected on the same.

Once the payment is processed, the customer is redirected back to the merchant Redirect URL.

Request format

All the HTTP requests to the payment platform submitted through REST API must use the POST method. This section covers the structure of such requests; for the information about structure of the data transferred inside the requests to API , see API Specification.

Structure

Each HTTP request to the payment platform must include the following elements:

The start line which contains the following: the HTTP method which always is POST, the endpoint in REST API (for instance /transactionServices/REST/v1/payments ), and the protocol, and its version (normally it is HTTP/1.1).
The header with the Host field that contains the domain name of the REST API, for instance,
- Test:
- Live:
The header with the authtoken field that contains the token value generated using the endpoint ( /transactionServices/REST/v1/authToken ) of the REST API , see Authentication for more details.
The message body, or payload, that contains request parameters in the form of UTF-8 with request data.

Addressing URL

The requests the merchant web service generates must include the basic and the relative addresses. The basic address for REST requests is Host Name; the relative address is the path to target endpoint in REST APIs.

Here is an example of the address for the payment status request: transactionServices/REST/v1/payments/{trackingid}

Authentication Parameter

The request header of the merchant web service must include the authtoken field and value in order to authenticate the request.

For more information about generating token, see Authentication Token .

Message body

The message body must contain request data in the <parameter name>: <parameter value> format. Set Content-Type as application/x-www-form-urlencoded

You can also pass the request in the JSON string follows the format <parameter name>:<parameter value>. Please make sure that you have set Content-Type as application/json

To secure data transfer you need to use the TLS 1.2 encryption protocol.

To prevent data eavesdropping when transferring data to the payment platform, you must generate the checksum and include this in the request body as described in the section of each APIs.

Response format

The payment platform responds with a HTTP response message to each request received from the web service on the same connection. The requested data of response body varies, depending on the interaction model and the result of request handling.

Structure

Each HTTP response to the web service includes the following elements:

The status line which contains the following: the protocol and its version (normally, it is HTTP/1.1), status code and reason phrase (for instance 200 OK).
Header fields.
The message body, or payload, that contains JSON or XML string (depending on Accept passed in request header) in the form of UTF-8 with response data.

Response Code

Response -codes are used in status line to inform about successful or failure request acceptance or execution as well as error causes. These response codes and reason phrases are defined in the following link Response Code.

Synchronous & Asynchronous responses

If the payment platform successfully handles the request, it responds with status line including 200 code, as well as response body including response data with response code.

If the payment platform cannot handle the request, it responds with the response body including status and extended response description with the response code that the payment platform provided and its description.

Callback format

In asynchronous interaction model, the payment platform returns intermediate and final results with callbacks to the web service URIs. Passed in the parameter notificationUrl

Each callback from the payment platform must include the following elements:

The start line which contains the following: the HTTP method which always is POST, the web service endpoints for callbacks with results (for instance, /notify), and the protocol, and its version (normally it is HTTP/1.1).
The header with the Host field that contains the domain name of the web service, for instance, (for instance, merchant.webservice.com).
The message body, or payload, that contains JSON string in the form of UTF-8 with result data including the signature.

Payment Statuses

Status description is the information about each transaction status. Various statuses and their status description you can check here.