Interaction concepts

Gate is an application programming interface (API) intended to accept requests from merchant's web services to the ECommPay payment platform. The Gate API conforms to the Representational State Transfer (REST) architectural style and is backward compatible, in other words, all components developed for any older version of Gate work correctly with the current version without changing program code on the web service side.

Gate can be accessed by using the following URL: https://api.ecommpay.com. Gate accepts requests that use the HTTP protocol, version 1.1 or higher and TLS of version 1.2 or higher. The Gate API specification is available at https://api-developers.ecommpay.com.

This section describes how to integrate by using Gate and covers technical integration aspects.

Integration steps

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

  1. Address the following organisational interaction issues with ECommPay:

    1. If your company has not yet obtained any ID or secret key from ECommPay, you need to submit an application for connecting to the ECommPay payment platform at https://ecommpay.com/apply-now/.
    2. 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. Consult your key account manager in ECommPay, if you need any assistance in completing Self-Assessment Questionnaire.
    3. Coordinate with the ECommPay technical support the process and timing of the integration, testing, and going live. When coordinating the process of testing, you can coordinate the possibility of testing procedures involving usage of payment cards, as well as usage of some alternative payment methods.
  2. Update the code of merchant's web service to implement the integration with the ECommPay payment platform through Gate.
  3. Test and put in production mode the updated web service code with specialists from the ECommPay technical support.

    Once testing and active monitoring phase is successfully complete, specialists from the ECommPay technical support provide regular support.

With any questions regarding usage of Gate contact ECommPay technical support service support@ecommpay.com.

Interaction models

The ECommPay payment 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. This interaction model supports two interaction models: synchronous and asynchronous. If the payment platform is able to respond to request without resorting to any third parties such as customer or external payment system, it uses the synchronous model; otherwise the payment platform uses the asynchronous model.

Synchronous model

The payment platform uses the synchronous interaction model when it can generate the response by using only its own data and resources, for instance to return the current status of payment. Synchronous interaction is performed in a single HTTP session and allows you to send only one response. Normally, the time between the payment platform receives the request issued by the web service and the payment platform sends out the response is less than 100 ms.

Figure: Synchronous request processing

Asynchronous model

The asynchronous interaction model is used when to generate response, the payment platform needs to communicate with third parties, for instance when it processes payment which requires input from customer and/or payment system.

In this model, the payment platform sends the following to merchant web service: acknowledgement that initial request is accepted and successfully validated and the callback with final result (in case initial request is successfully validated). The model may also include exchange of messages with intermediate results between those two responses, for instance the payment platform may issue redirect to a form exposed by payment system.

Normally, the time between web service issues the initial request and the ECommPay payment platform sends out the first response is less than 100 ms; though, the time between request receiving and callback sending may vary depending on third parties that are involved in request processing.

Figure: Asynchronous request processing

To ensure correct asynchronous interaction with the payment platform, you need to properly implement reaction to callbacks you obtain from the payment platform. The reaction to the callbacks with intermediate results depends on the information the callbacks contain while the reaction to the callback with final result require send the receipt acknowledgement HTTP response:

  • If the callback was successfully processed, specify HTTP 200 OK status code. The response may not include a response body.
  • If an error was detected while handling a callback, specify HTTP error status code. It is recommended to provide one that are clearly defined the type of error and registered in the HTTP specification.

The payment platform sends callbacks while web service returns the 200 OK response.

Figure: Response to callback

HTTP/1.1 200 OK
Date: Fri, 07 Jun 2019 11:38:32 GMT
Content-Type: text/plain;charset=UTF-8
Content-Length: 2
Connection: keep-alive
                    
OK

Request handling

Within any interaction models interaction begins with a request which is sent from the web service to the ECommPay payment platform. When the payment platform receives a request, there are three stages in the lifetime of request handling as follows:

  • On the stage of request acceptance, the payment platform performs various preliminary tasks including reading and parsing a JSON string contained in the request, as well as checking for the minimum number of parameters in JSON.
    • If the payment platform is able to parse the JSON string and the minimum number of parameters is specified the JSON, the request is sent through to the stage of request processing. If the payment platform uses an asynchronous model, the payment platform sends a HTTP response with information that the request has been accepted for processing.
    • If the payment platform encounters errors, the request handling is stopped. Within any interaction models, the payment platform sends a HTTP response showing error condition.
  • During the stage of request processing the payment platform performs Gate specification compliance checks, as well as data semantic consistency checks and signature validity.
    • If the payment platform does not encounter errors in the data extracted from the JSON string, the request is sent through to the stage of request execution. In this case, the payment platform does not send a HTTP response. For the request initiating a payment, a payment is registered in the platform and a payment object is created.
    • If the payment platform encounters errors in the data, the request handling is stopped. If the payment platform uses a synchronous model, the payment platform sends a HTTP response showing error condition; if the payment platform uses an asynchronous model, it sends a callback.
  • During the stage of request execution the payment platform performs Gate specification compliance checks, as well as data semantic consistency checks and signature validity.
    • If the payment platform successfully executes the request, it returns result. If the payment platform uses a synchronous model, it responds with an HTTP response with the result; if the payment platform uses an asynchronous model, it responds with a callback with the result.
    • If the payment platform unsuccessfully executes the request, it stops request handling and returns error result. If the payment platform uses a synchronous model, it responds with an HTTP response with the requested data; if the payment platform uses an asynchronous model, it responds with a callback with the result.

Normally, the time between the payment platform receives the request and it responds with the first response is less than 100 ms in any cases. If no response is received, the web service may repeat the request with the same data (and the same payment identifier for payment processing request). In case of 4xx error response, the web service should resend the request with a new or replaced data.

Request format

All the HTTP requests to the payment platform submitted through Gate 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 Gate, see API.

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 Gate (for instance /v2/payment/status), 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 Gate API (for instance, api.ecommpay.com).
  • An empty line which serves as a separator between the message header and the body.
  • The message body, or payload, that contains JSON string in the form of UTF-8 with request data including the signature.

Besides the mandatory Host field, the header may include any other fields supported by HTTP version 1.1. Below you will find a sample HTTP request with recommended header fields. The JSON string is formatted for better readability.

Figure: HTTP request that contains a request for payment status in the payment platform

POST /v2/payment/status HTTP/1.1
User-Agent: curl/7.29.0
Host: api.ecommpay.com
Accept: */*
Content-Length: 179
Content-Type: application/x-www-form-urlencoded
                    
{
    "general": {
    "project_id": 1,
    "payment_id": "ID_184",
    "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tawY3T\/pOMeSaRfBaNIipTv+AWoXW\...=="
  }
}

Addressing parameters

The requests the merchant web service generates must include the basic and the relative addresses. The basic address for Gate requests is api.ecommpay.com; the relative address is the path to target endpoint in Gate.

Note: Therefore, the complete address takes the following format: https://{<Gate domain name>}/{<target endpoint path>}. Here is an example of the address for the payment status request: /v2/payment/status. Normally, the complete addresses are not used for generating POST requests.

Message body

The message body must contain request data in the JSON format. The JSON string follows the format "<parameter name>": <parameter value>. To prevent data eavesdropping when transferring data to the payment platform, you must sign messages and include the signature inside the request data. Also, to secure data transfer you need to use the TLS 1.2 encryption protocol. For more information about generating signature, see Signature generation and verification.

Here is an example of a JSON code with all the information to request current payment status from the payment platform. Because this is the status request, you do not need to specify payment amount and currency.

Figure: Payment information encapsulated inside JSON object

{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    }

Response format

The ECommPay 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, as follows:

  • Requested data, only if the payment platform successfully handles the request and uses a synchronous model.
  • Information that request is accepted for processing, only if the payment platform successfully accept the request for processing and uses a synchronous model.
  • extended error description, if the payment platform cannot handle the request using a synchronous model or cannot accept the request for processing using an asynchronous model.

This section covers the structure of such responses, as well as their status codes and statuses used to indicate the request status; for the information about the ECommPay unified response codes used in the data transferred inside the responses to web service, see Information of operations performing.

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.
  • An empty line which serves as a separator between the message header and the body.
  • The message body, or payload, that contains JSON string in the form of UTF-8 with response data.

Status code

Status codes are used in status line to inform about successful or failure request acceptance or execution as well as error causes. These status codes and reason phrases are listed in the following table.

Status code Description
200 OK

Synchronous model: The request has been successfully executed. The response body has the requested data.

Asynchronous model: The request has been successfully accepted. The response body has the requested result. You can expect callbacks with intermediate or final results.

400 Bad Request The request can not be accepted because of missing mandatory parameter in JSON string, for instance a project identifier.
403 Forbidden The request can not be accepted because access to the requested (valid) endpoint is forbidden, for instance not IP address not in white list error.
422 Unprocessable Entity The request can not be accepted because of malformed syntax in JSON string, for instance missing comma.
500 Internal Error The request can not be processed because of the payment platform error.

Request status

Response body may include the status parameter to inform that the request is accepted or is not accepted for processing. There are two statuses:

  • success—the request is accepted for processing. This status is specified in responses with 200 status-code only if the payment platform handles request asynchronously.
  • error—the request is not accepted for processing. This status is specified in responses with 400, 403, 422 and 500 status-code for asynchronous and synchronous request handling.

Synchronous responses

This section covers sample responses to request synchronously handled. JSON string is formatted for better readability.

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

Figure: Response to request that successfully handled

POST /v2/payment/status HTTP/1.1        // The web service request for checking the payment status
                    
HTTP/1.1 200 OK                                  // The payment platform response
Server: api.ecommpay.com
Date: Wed, 22 May 2019 10:27:49 GMT    
Content-Type: application/json; charset=UTF-8
Content-Length: 875
Connection: keep-alive
Keep-Alive: timeout=60
Cache-Control: no-cache
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Origin: *
X-Powered-By: PHP/7.0.32
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,
X-Requested-With,If-Modified-Since,Cache-Control,Content-Type
Expires: Wed, 22 May 2019 10:27:48 GMT

{
	"project_id":665,
	"payment":{
		"id":"E2E__S02_0.53381200_1558520409",
		"type":"purchase","status":"success",
		"date":"2019-05-22T10:20:20+0000",
		"method":"cup-card",
		"sum":{
			"amount":100,
			"currency":"CNY"
		},
	"description":"Success from PP"
	},
	"account":{
		"number":"628888******8888"
	},
	"customer":{
		"id":"Vally Vasya"
	},
	"operations":[{
		"id":3259141213429,
		"type":"sale",
		"status":"success",
		"date":"2019-05-22T10:20:20+0000",
		"created_date":"2019-05-22T10:20:13+0000",
		"request_id":"e0d69edf1c3aac249e",
		"sum_initial":{
			"amount":100,
			"currency":"CNY"
		},
	"sum_converted":{
		"amount":100,
		"currency":"CNY"
	},
	"provider":{
		"id":1379,
		"payment_id":"1558520414466",
		"date":"2019-05-22T10:20:14+0000",
		"auth_code":""
	},
	"code":"0",
	"message":"Success"
	}],
	"signature":"p6BvZTmzzzUSaN06OVT2SNxTJWvm6\/GEOSEMvUaKgLGzVO5VpKKWt27rq\
	/D1HulyqMGvV0+yN6ixICqSW3oCeA=="
}

If the payment platform cannot handle the request, it responds with status line including error code (for instance 422), as well as response body including error status and extended error description with the error code that the payment platform provided (for instance 2003) and its description (for instance Invalid JSON string).

Figure: Response to request that cannot be handled

POST /v2/payment/status HTTP/1.1         // The web service request for checking the payment status
                    
HTTP/1.1 422 Unprocessable Entity                 // The payment platform response
Server: nginx/1.14.2
Date: Thu, 30 May 2019 09:44:26 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/7.0.33
Expires: Thu, 30 May 2019 09:44:25 GMT
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,
User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type

{
	"status":"error",
	"code":"2003",
	"message":"Invalid JSON string"
}

Asynchronous responses

This section covers sample responses to request asynchronously handled. JSON string is formatted for better readability.

If the payment platform successfully accepted the request for processing, it responds with status line including 200 code, as well as response body including the success status.

Figure: Response to request that successfully accepted for processing

POST /v2/payment/card/auth HTTP/1.1        // The web service request for holding funds
                    
HTTP/1.1 200 OK                                     // The payment platform response
Server: nginx/1.14.2
Date: Thu, 30 May 2019 09:52:16 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/7.0.33
Expires: Thu, 30 May 2019 09:52:15 GMT
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,
X-Requested-With,If-Modified-Since,Cache-Control,Content-Type

{
	"status":"success",
	"request_id":"e7cdefae67068d",
	"project_id":69,
	"payment_id":"ORDER_ID__sendPurchase_dcc_1"
}

If the payment platform cannot handle the request, it responds with status line including error code (for instance 400), as well as response body including error status and extended error description with the error code that the payment platform provided (for instance 2004) and its description (for instance Required field not provided).

Figure: Response to request that cannot be accepted for processing

POST /v2/payment/card/auth HTTP/1.1    // The web service request for holding funds
                    
HTTP/1.1 400 Bad Request                        // The payment platform response
Server: nginx/1.14.2
Date: Thu, 30 May 2019 09:23:23 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/7.0.33

{
	"status":"error",
	"code":"2004",
	"message":"Required field not provided"
}

Callback format

In asynchronous interaction model, the ECommPay payment platform returns intermediate and final results with callbacks to the web service URIs. This section covers the structure of callbacks; for detailed information about callbacks, see Callbacks.

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/success), 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, webservice.com).
  • An empty line which serves as a separator between the message header and the body.
  • The message body, or payload, that contains JSON string in the form of UTF-8 with result data including the signature.

Below you will find a sample callback with payment result. JSON string is formatted for better readability.

Figure: Callback with payment result

POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: webservice.com

{
	"account":{
		"number":"421234******1234",
		"token":"1234567890",
		"type":"visa",
		"card_holder":"TEST TEST",
		"id":1234,"expiry_month":"**",
		"expiry_year":"****"
	},
	"customer":{
		"id":"12345",
		"phone":"***********"
	},
	"payment":{
		"date":"2019-06-07T11:38:31+0000",
		"id":"1234567890",
		"method":"card",
		"status":"success",
		"sum":{
			"amount":175000,
			"currency":"RUB"
		},
		"type":"purchase",
		"description":"Deposit to 1234567890"
	},
	"project_id":25,
	"processingDateTime":"2019-06-07T11:38:30+0000",
	"country":"RU",
	"product_name":"Visa",
	"issuer_name":"",
	"operation":{
		"id":1234567890,
		"type":"sale",
		"status":"success",
		"date":"2019-06-07T11:38:32+0000",
		"created_date":"2019-06-07T11:37:56+0000",
		"request_id":"1234567890-1234567890",
		"sum_initial":{
			"amount":175000,
			"currency":"RUB"
		},
		"sum_converted":{
			"amount":175000,
			"currency":"RUB"
		},
		"provider":{
			"id":11,
			"payment_id":"098765432",
			"date":"2019-06-07T11:38:30+0000",
			"auth_code":"","endpoint_id":1
		},
		"code":"0",
		"message":"Success",
		"eci":"05"
	},
	"signature":"qwertyuioiuytrewqwertyuu123434"
}