# Interaction concepts {#en_gate_interaction_organisation}

An article about organising the work with Gate on the web service side based on the principles of the payment platform operation and the utilised interaction flows and formats.

Gate is an application programming interface \(API\) intended to accept requests from merchant's web services to the Ecommpay payment platform. Gate 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 specification is available at [https://api-developers.ecommpay.com](https://api-developers.ecommpay.com).

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

**Parent topic:**[Gate](en_Gate_Integration_About.md)

## Integration steps {#en_gate_integration_step}

To integrate with the Ecommpay payment platform by using Gate, the merchants should do the following:

1.  Address the following organisational issues of interaction with Ecommpay:

    1.  If the company has not obtained the project identifier or a secret key from Ecommpay, submit [the application](https://ecommpay.com/apply-now/) for connecting to the Ecommpay payment platform.
    2.  For processing payments made with the Visa and Mastercard cards, provide the Ecommpay key account manager with the documents of compliance with [the PCI DSS requirements](en_faq_integration.md#fig_fgk_rgs_4nb). The following documents are required:
        -   From all merchants—[the ASV scan](en_glossary.md) report.

            ASV scanning must be performed by the authorised scanning service providers \(PCI SSC Approved Scanning Vendor, ASV\) quarterly and after every significant change in the network infrastructure.The Ecommpay merchants can select these providers on their own and, if relevant, involve a provider that is in partnership with Ecommpay. To have the scanning services via the partner organised, contact the key account manager.

        -   From the merchants processing over 6 million operations annually \(Level 1\)—the Attestation of Compliance, AOC.
        -   From the merchants processing to 6 million operations annually \(Levels 2, 3, and 4\)—[the Self-Assessment Questionnaire](https://www.pcisecuritystandards.org/pci_security/completing_self_assessment), SAQ.

            With questions on completing the questionnaire, contact the Ecommpay key account manager.

    3.  Coordinate the procedures of integrating with the payment platform, testing\(including testing various payment methods\), and launching the functionality with the Ecommpay technical support specialists.
2.  Update the code of the web service to integrate with the Ecommpay payment platform by using Gate.
3.  Test the integration solution and launch it in coordination with the Ecommpay technical support specialists.

    Upon testing and monitoring, in case of correct payment processing in the production mode, the Ecommpay technical support specialists interact with the web service in the full-time support mode.


With any questions about using Gate, contact the Ecommpay key account manager and technical support specialists \([support@ecommpay.com](mailto:support@ecommpay.com)\).

## Interaction models {#en_gate_interaction_scheme}

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 {#section_bc4_fsh_thb .section}

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.

![](images/en_gate_sync.svg "Synchronous request processing")

### Asynchronous model {#section_sdm_hsh_thb .section}

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

![](images/en_gate_async.svg "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
```

## Request handling {#en_gate_requests_processing_scheme}

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.

## Data formats {#en_Gate_Formats}

### Overview {#section_hgq_qwb_wvb .section}

When working with the Gate API, as well as other interfaces of the Ecommpay payment platform, you should use only the permitted data encoding methods and formats.General information about them can be found in this article and [the Gate API specification](https://api-developers.ecommpay.com/). In addition, you can use the specialised [references](en_directory.md), descriptions of specific payment methods in the [corresponding section](en_pm_about.md), and articles about additional capabilities. Besides, you can contact the Ecommpay support specialists with any questions about data formats that arise.

### Data encoding {#section_kkg_kjl_bbb .section}

The generation of requests sent to the platform and the processing of responses and callbacks received from the platform must be carried out with the use of the UTF-8 encoding. In addition, in some cases you have to use other encoding methods, for example, Base64.Such cases are stipulated in this documentation and [the Gate API](https://api-developers.ecommpay.com/) specification.

### Dates and times {#section_db4_ckl_bbb .section}

In the scope of interaction with the platform, dates and times are usually represented in the `YYYY-MM-DDThh:mm:ss±hh:mm` format \(according to the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) requirements\), where `YYYY-MM-DD` is a date, `T` is a separating character, `hh:mm:ss` is time, `hh:mm` is a UTC \(Coordinated Universal Time\) offset. For example, `2025-05-25T15:30:25+00:00`.

Along with that, in some cases the date and time format can differ from the described above.Such cases are stipulated in this documentation and [the Gate API](https://api-developers.ecommpay.com/) specification.

### Amounts {#section_okf_xjl_bbb .section}

In the scope of interaction with the platform, payment and operation amounts are specified, as a rule, in the smallest units of currency and with no decimal separator. For example, 100 US dollars are represented in cents and specified as 10000 \(not as 100 or as 100.00\).The examples of other currencies representation are provided in the table.

|Currency|Amount|Representation|
|--------|------|--------------|
|EUR|39.95|`3995`|
|GBP|450.66|`45066`|
|JPY|200|`200`|
|KWD|150.155|`150155`|

The number of decimal digits for different currencies is defined according to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard and provided [in the reference with currency codes](en_currency_codes.md).

### Currency, country, and language codes {#section_iq3_dkl_bbb .section}

In the scope of interaction with the Ecommpay payment platform, the following codes can be used:

-   three-letter *currency codes*—according to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard
-   two-letter *country codes*—according to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) standard
-   single-, two-, and three-character *territory codes* \(such as states, provinces, and regions\)—according to the [ISO 3166-2](https://www.iso.org/iso-3166-country-codes.html) standard
-   two-letter *language codes*—according to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard

These codes, except for territory codes, can be found [in the references](en_directory.md).

## Request format {#en_gate_requests_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](https://api-developers.ecommpay.com/).

### Structure {#section_chd_1p2_xhb .section}

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](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-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](https://tools.ietf.org/html/rfc2616#page-31). 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 {#section_b3q_bsx_thb .section}

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](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status). Normally, the complete addresses are not used for generating POST requests.

### Message body {#section_kdx_ptx_thb .section}

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](en_platform_signature.md).

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

## Response format {#en_gate_responses_format}

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 [Handling operation processing information](en_platform_payment_info_codes.md).

### Structure {#section_c2t_tbm_xhb .section}

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 {#section_aj3_knq_13b .section}

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.

|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 cannot be accepted because of the missing mandatory parameter in JSON string, for instance, a project identifier.|
|403 Forbidden|The request cannot be accepted because access to the requested \(valid\) endpoint is forbidden, for instance, when the IP address from which the request has been sent is not allowed.|
|422 Unprocessable Entity|The request cannot be accepted because of malformed syntax in JSON string, for instance, a comma is missing.|
|500 Internal Error|The request cannot be processed because of the payment platform error.|

### Request status {#section_jmx_knq_13b .section}

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 {#section_rn2_tm2_yhb .section}

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

```
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 {#section_zxw_5m2_yhb .section}

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

## Callback format {#en_gate_callbacks_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 [Handling callbacks](en_platform_callbacks.md).

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.

```
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":"431422******0056",
		"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":1750,
			"currency":"EUR"
		},
		"type":"purchase",
		"description":"Deposit to 1234567890"
	},
	"project_id":25,
	"processingDateTime":"2019-06-07T11:38:30+0000",
	"country":"GB",
	"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":1750,
			"currency":"EUR"
		},
		"sum_converted":{
			"amount":1750,
			"currency":"EUR"
		},
		"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"
}
```