Interaction concepts

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.

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

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.

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.

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.

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

The ecommpay payment platform responds with an HTTP response message to each request received from the web service within the same HTTP session. The requested data of the response body varies depending on the interaction model and the result of request handling. The response can contain the following:

• Requested data—if the payment platform successfully handles the request and uses a synchronous model.
• Information that request is accepted for processing—if the payment platform successfully accepts the request for processing and uses an asynchronous 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 information about the unified response codes used in the data transferred within the responses, see Information of operations performing.

Structure

Each HTTP response to the web service includes the following elements in the given order:

• The status line which contains the following: the protocol and its version (usually, 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 UTF-8 encoding with response data.

Status code

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

Request status

Response body may include the status parameter to communicate that the request has been or has not been 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-codes for both asynchronous and synchronous request handling.

Synchronous responses

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

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

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 the status line including error code (for instance 422) as well as the 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).

Asynchronous responses

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

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

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

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"
}