Общий порядок интеграции

При использовании Gate взаимодействие между веб-сервисом и платежной платформой Rocketpay строится на обмене HTTP-сообщениями по принципу «запрос-ответ»: веб-сервис отправляет запросы и получает ответы от платформы. Платформа поддерживает две схемы взаимодействия:

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

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

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

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

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

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

Время от получения запроса до отправки начального ответа, как правило, составляет не более 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 все данные от веб-сервиса должны передаваться в запросах (requests) — HTTP-сообщениях заданной структуры — с использованием метода POST. Описание общей структуры запросов представлено далее, а описание структур данных для различных случаев — в спецификации интерфейса.

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

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

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

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

POST /v2/payment/status HTTP/1.1
User-Agent: curl/7.29.0
Host: https://api.rocketpay.kz
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.rocketpay.kz, а в качестве относительного — указатель конечной точки в интерфейсе Gate в соответствии со спецификацией.

Тело запроса

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

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

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

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

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

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

Структура ответа

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

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

HTTP-коды ответов

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.example.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":"John Doe"
	},
	"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"
}