Организация взаимодействия

При использовании Gate взаимодействие между веб-сервисом и платёжной платформой ecommpay строится на обмене HTTP-сообщениями по принципу «запрос-ответ» — с отправкой запросов от веб-сервиса и ответов от платформы. При этом предусмотрены две схемы взаимодействия: синхронная для тех запросов, которые могут быть выполнены автономно на стороне платформы, и асинхронная для тех запросов, выполнение которых зависит не только от работы платформы, но и от действий других сторон (например, пользователя или платёжной системы).

Синхронная схема

Синхронная схема взаимодействия используется, когда запрос можно полностью выполнить на стороне платёжной платформы: например, чтобы получить статус платежа в платформе. Такое взаимодействие осуществляется в рамках одного HTTP-сеанса и подразумевает отправку одного ответа на полученный запрос. Это может быть ответ с запрошенной информацией или с информацией об ошибке. Время от получения запроса до отправки ответа, как правило, составляет не более 100 мс.

Асинхронная схема

Асинхронная схема взаимодействия используется, когда выполнение запроса требует участия других сторон помимо веб-сервиса и платёжной платформы: например, чтобы провести оплату с участием пользователя и платёжной системы.

В рамках такой схемы от платформы к веб-сервису отправляются начальный ответ (с информацией о том, что запрос получен и корректен, либо о том, что он некорректен) и итоговое оповещение с информацией (если запрос корректен). Также в ходе проведения платежа могут отправляться промежуточные оповещения: например, с информацией для перенаправления пользователя к форме платёжной системы.

Время от получения запроса до отправки начального ответа, как правило, составляет не более 100 мс. Время от приёма запроса до отправки оповещений может варьироваться, поскольку зависит от других сторон, задействованных в выполнении запроса.

Для организации взаимодействия с платёжной платформой по асинхронной схеме на стороне веб-сервиса необходимо обеспечить корректное реагирование на оповещения. Для промежуточных оповещений способы реагирования зависят от переданных сведений, а для итогового оповещения необходимо отправить ответ о его приёме:

• Если оповещение обработано успешно, необходимо указать код ответа 200 OK, при этом тело ответа может быть пустым.
• Если при обработке оповещения выявлена ошибка, рекомендуется указать код ответа, соответствующий этой ошибке, из числа доступных в спецификации HTTP.

Оповещения отправляются повторно до получения ответа от веб-сервиса с кодом 200 OK.

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

В рамках взаимодействия с платёжной платформой через Gate все данные от веб-сервиса должны передаваться в запросах — HTTP-сообщениях заданной структуры — с использованием метода POST. Описание общей структуры запросов представлено далее, а описание структур данных для различных случаев — в спецификации интерфейса.

Структура

В каждом запросе к платёжной платформе должны передаваться следующие элементы в указанном порядке:

• стартовая строка с указанием метода передачи запроса (POST) и конечной точки в интерфейсе Gate (например, /v2/payment/status), протокола и его версии (HTTP/1.1);
• заголовок с полем Host, содержащим доменное имя для запросов через Gate (api.ecommpay.com);
• пустая строка — разделитель, отделяющая служебную информацию от тела сообщения;
• тело сообщения, содержащее JSON-строку в кодировке UTF-8 с набором данных и подписью к ним.

В дополнение к обязательному полю Host в заголовке можно использовать любые другие поля из числа допустимых в HTTP версии 1.1. Далее представлен пример запроса с рекомендуемым набором полей заголовка. Содержимое JSON-строки в этом примере разбито на несколько строк для удобства чтения.

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\/UG0Di8hTng6JvC7vQsaC6tY3T\/pOMeSaRfBa...=="
    }
}                

Параметры адресации

При формировании запросов необходимо указывать базовый и относительный адреса отправки. В качестве базового адреса для запросов через Gate используется доменное имя api.ecommpay.com, а в качестве относительного — указатель конечной точки в интерфейсе Gate в соответствии со спецификацией.

Тело

В теле сообщения должна содержаться JSON-строка с набором данных в формате "<название параметра>": <значение параметра>. Чтобы предотвратить утечку и подмену данных во время их передачи в платёжную платформу, в составе JSON-строки используется подпись, а на транспортном уровне передачи — протокол TLS 1.2, обеспечивающий шифрование. Подробная информация о формировании подписи представлена в разделе Работа с подписью.

Далее представлен пример JSON-строки c набором данных, обязательных для получения статуса платежа. Сумму и валюту платежа для данного запроса указывать не требуется.

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

Со стороны платёжной платформы получение запроса подтверждается отправкой ответа — HTTP-сообщения заданной структуры — в рамках того же сеанса. В зависимости от результата обработки запроса и схемы взаимодействия между веб-сервисом и платформой передаваемые в ответе данные включают в себя:

• запрошенную информацию, если запрос выполнен в рамках синхронной схемы;
• сведения о приёме запроса, если запрос принят в обработку в рамках асинхронной схемы;
• расширенное описание ошибки, если запрос не может быть выполнен в рамках синхронной схемы или не может быть принят в обработку в рамках асинхронной.

Далее представлена информация о структуре ответов, а также о кодах и статусах, используемых для передачи информации о состоянии запроса; информация о полном перечне кодов платёжной платформы, используемых в расширенном описании ошибок представлена в разделе Информация об операциях.

Структура

В каждом ответе от платформы содержатся следующие элементы в порядке перечисления:

• стартовая строка с указанием протокола и его версии (HTTP/1.1), кода ответа и поясняющей фразы к коду (например, 200 OK);
• поля заголовка;
• пустая строка — разделитель, отделяющая служебную информацию от тела сообщения;
• тело сообщения, содержащее JSON-строку в кодировке UTF-8 в с набором данных.

Коды ответа

HTTP-код ответа используется в стартовой строке любого ответа для передачи информации о результате приёма или выполнения запроса либо о причине обнаруженной ошибки. Перечень кодов ответов и пояснительных фраз, используемых в ответах платформы, приведён далее в таблице.

Статусы запроса

Статус запроса используется для передачи информации о приёме запроса в обработку и указывается в параметре status в теле ответа. Для запроса используется два статуса:

• success — запрос принят в обработку. Данный статус используется только в рамках взаимодействия по асинхронной схеме в ответах с HTTP-кодом 200.
• error — запрос не может быть принят в обработку. Данный статус может использоваться в рамках обеих схем взаимодействия в ответах с кодами ошибок 400, 403, 422 и 500.

Ответы с запрошенной информацией

В этом пункте представлены примеры ответа на запрос, обрабатываемый по синхронной схеме. Содержимое JSON-строки в этих примерах разбито на несколько строк для удобства чтения.

Если запрос успешно обработан, то в стартовой строке ответа передаётся код ответа 200, а в теле ответа — запрошенная информация без указания статуса запроса.

POST /v2/payment/status HTTP/1.1        // Запрос от веб-сервиса на получение статуса платежа в платформе
                    
HTTP/1.1 200 OK                                  // Ответ от платёжной платформы
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=="
}

Если в запросе обнаружена ошибка, то в стартовой строке ответа указывается код ответа с причиной ошибки (в примере — 422), а в теле — статус error и расширенная информация об ошибке: код ошибки в платёжной платформе (в примере —2003) и описание к нему (в примере — Invalid JSON string).

POST /v2/payment/status HTTP/1.1         // Запрос от веб-сервиса на получение статуса платежа в платформе
                    
HTTP/1.1 422 Unprocessable Entity                 // Ответ от платёжной платформы
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"
}

Ответы с результатом приёма

В этом пункте представлены примеры ответа на запрос, обрабатываемый по асинхронной схеме. Содержимое JSON-строки в этих примерах разбито на несколько строк для удобства чтения.

Если запрос принят в обработку, то в стартовой строке ответа указывается код ответа 200, а в теле — статус success.

POST /v2/payment/card/auth HTTP/1.1         // Запрос от веб-сервиса 
                                                    на предварительную блокировку средств
                    
HTTP/1.1 200 OK                                     // Ответ от платёжной платформы
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"
}

Если в запросе обнаружена ошибка, то в стартовой строке ответа указывается код ответа с причиной ошибки (в примере — 400), а в теле — статус error и расширенная информация об ошибке: код ошибки в платёжной платформе (в примере —2004) и описание к нему (в примере — Required field not provided).

POST /v2/payment/card/auth HTTP/1.1     // Запрос от веб-сервиса 
                                                    на предварительную блокировку средств
                    
HTTP/1.1 400 Bad Request                        // Ответ от платёжной платформы
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"
}