Инструменты страницы
Алгоритм создания запроса оплаты
1. Сделать запрос ключа
Для этого в адресной строке необходимо ввести:
https://{domain_name}/payment/se/keys.do
и нажать кнопку Enter.
keyValue
В результате получаем ключ в следующем формате:
{«keys»:[{«keyValue»:«—–BEGIN PUBLIC KEY—–MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAowJuD3dwynQjgEnKDjEZo6fLqSzG4A1Q8x2aV43IUKNKmYZnDeIFoHOkSKOHBsJO5f0F0Z8/dqxYxpF3aFOR3gJLJIC+YG0nSa31nAo+Bw0KQtIVnYtJc1tdyGQGlP4bnRGPIikIZJI3D4yRw4VFk6T6sfpUbP6gqvOfznMkiD1CgLYSLpGM8SXr7ColrF7m/UGprwLdnVjd/5xDzj1bB6YHAZsdDAdvCC3c97o3KmYgmeuMHkAtTPvtn8JHn4CRymDhXrU+LCpCTvoEY8Pi9623ai0Mrv0k+OMLy2XSVrXRaw3v7SZNuhrM0cpij7XbNc5cBefrHfrTmMMhyBliTQIDAQAB—–END PUBLIC KEY—–»,«protocolVersion»:«RSA»,«keyExpiration»:1598527672000},
{«keyValue»:«—–BEGIN PUBLIC KEY—–MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAowJuD3dwynQjgEnKDjEZo6fLqSzG4A1Q8x2aV43IUKNKmYZnDeIFoHOkSKOHBsJO5f0F0Z8/dqxYxpF3aFOR3gJLJIC+YG0nSa31nAo+Bw0KQtIVnYtJc1tdyGQGlP4bnRGPIikIZJI3D4yRw4VFk6T6sfpUbP6gqvOfznMkiD1CgLYSLpGM8SXr7ColrF7m/UGprwLdnVjd/5xDzj1bB6YHAZsdDAdvCC3c97o3KmYgmeuMHkAtTPvtn8JHn4CRymDhXrU+LCpCTvoEY8Pi9623ai0Mrv0k+OMLy2XSVrXRaw3v7SZNuhrM0cpij7XbNc5cBefrHfrTmMMhyBliTQIDAQAB—–END PUBLIC KEY—–»,«protocolVersion»:«RSA»,«keyExpiration»:1661599747000}]}
Где:
- – строковое представление публичного ключа RSA 2048
keyExpiration
- – планируемый срок действия ключа, дата в секундах по стандарту UNIX time
protocolVersion'' – версия алгоритма шифрования
-
2. Регистрация заказа
3. Сформировать строку, которую необходимо зашифровать
В нашем примере в качестве UUID указан orderId = b94eac90-e487-796a-8ed2-cf5a00096352. Получаем строку:
2020-09-15T10:00:33+03:00/9bb1501a-1547-425a-a022-1db5ff8f72c4/5555555555555599/123/202412/b94eac90-e487-796a-8ed2-cf5a00096352
4. Зашифровать полученную строку
Получившуюся строку необходимо зашифровать, используя алгоритм RSA шифрования «RSA/None/PKCS1Padding» с ключом длиной 2048.
Пример результата шифрования:
Cfqv4t2XHBb9k8ixM7jxxCvziETS4koa3bV3F0QUvGVY47nKyMBqjGzV/rvmCAw6KzwoBDzeLsqwBLEzvQhaF627ZS0OJnhttBi4fL3/h/sBSwFtxr3s+oVUeoE3e4SNVUq9vciinOyNCIKqfpeQya+pOUYt3MgrtSeu66Ar12XEj4k6lecZN7Ffquj9RqhZsYhP63np5VCxJR90cNQG+TMWIFU6rqxLAe4gzCJtcXNrPT8aDOI201Zwd+e4K1YnrI7dZGlibO7MVMPB9m7NJaJTHko/MiJNWumAjS4yDDovLraIKMwOFTvAhqXsHslthpcUO0GZXEIaDRgERD7+jw==
5. Производим запрос paymentOrder с указанием seToken
Запрос оплаты заказа (paymentOrder c seToken)
В настоящем документе при описании параметров запросов и ответов используются следующие обозначения типов данных:
- A<n> – последовательность латинских букв длины <n>;
- A..<n> – последовательность латинских букв длиной, не превышающей <n>;
- N<n> – последовательность цифр длины <n>;
- N..<n> – последовательность цифр длиной, не превышающей <n>;
- AN<n> – последовательность латинских букв и цифр фиксированной длины <n>;
- AN..<n> – последовательность латинских букв и цифр длиной, не превышающей <n>;
- ANS<n> – последовательность латинских букв, цифр и символов фиксированной длины <n>
- ANS..<n> – последовательность латинских букв, цифр и символов длиной, не превышающей <n>;
- UTC – дата и время, при этом: дата должна быть передана без указания часового пояса, время московское, для протокола SOAP используется стандартная кодировка xs:dateTime.
Параметры запроса:
Название | Тип | Обязательно | Описание | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
ANS36 | Да |
Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа не удалась по причине ошибки, детализированной в errorCode. |
|||||||||
|
N12…19 | Да |
Номер платёжной карты. При указании в запросе параметра seToken этот параметр не обязателен к передаче. |
|||||||||
|
N3 | Да |
Код CVC/CVV2 на обратной стороне карты. При указании в запросе параметра seToken этот параметр не обязателен к передаче. |
|||||||||
year | N4 | Да | Год окончания действия срока карты. | |||||||||
month | N2 | Да | Месяц расчётного периода в формате MM . |
|||||||||
|
AS..26 | Да |
Имя держателя карты латиницей, если доступно. Длина поля ограничена 26 символами (латинские буквы, точка, пробел). |
|||||||||
|
A2 | Да |
Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию. |
|||||||||
|
AN..8192 | Нет | Шифрованное значение платежных данных, введённых клиентом на стороне ТСП | |||||||||
|
ANS..39 | Нет |
IP-адрес покупателя. IPv6 поддерживается во всех запросах (до 39 символов). |
|||||||||
|
ANS..40 | Нет |
Адрес электронной почты покупателя. |
|||||||||
|
См. столбец с описанием. | Нет |
Дополнительный тег с атрибутами для передачи дополнительных параметров. Поля дополнительной информации для последующего хранения. Данные поля могут быть переданы на обработку банком для последующего отображения в реестрах. По умолчанию на обработку банком передаются поля номер заказа orderNumber и его описание orderDescription (не более 99 символов, запрещены к использованию «%» (процент), «+» (плюс), «\r» (конец строки) и «\n» (перенос строки)).
Включение данного функционала возможно по согласованию с банком в период интеграции. Для передачи N параметров, в запросе должно находиться N тегов
В параметре запрещено передавать зарезервированные имена (в случае их передачи заказ может быть отклонен):
|
|||||||||
|
См. описание | Нет |
Блок c регистрационными данными клиента (адрес, почтовый индекс), необходимыми для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если активна соответствующая пермиссия для мерчанта («Разрешено использование AVS/AVV»). |
billingPayerData
Параметры блока billingPayerData
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
AN..50 | Нет |
Город, зарегистрированный по конкретной карте у Банка Эмитента |
|
AN..50 | Нет |
|
|
AN..50 | Нет |
Адрес, зарегистрированный по конкретной карте у Банка Эмитента Строка 1. Обязательно, если у Мерчанта активирована пермиссия «Разрешено использование AVS/AVV». |
|
AN..50 | Нет |
Адрес, зарегистрированный по конкретной карте у Банка Эмитента Строка 2. |
|
AN..50 | Нет |
Адрес, зарегистрированный по конкретной карте у Банка Эмитента Строка 3. |
|
AN..50 | Нет |
Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно, если у Мерчанта активирована пермиссия «Разрешено использование AVS/AVV». |
|
AN..50 | Нет |
Штат, зарегистрированный по конкретной карте у Банка Эмитента (ISO 3166-2) |
** По умолчанию в процессинг банка передаются поля номер заказа orderNumber и его описание description (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n)
Параметры ответа:
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
N..2 | Да |
Код ошибки. |
|
|
Нет |
|
|
ANS..* | Нет |
При успешном ответе. Результат попытки оплаты. Возможные значения представлены ниже.
|
|
ANS..* | Нет |
При успешном ответе. В случае платежа без необходимости аутентификации на ACS – URL, на который производится переадресация после платежа. В случае 3DS-платежа – URL для возврата с ACS. |
|
AN..512 | Нет |
Адрес перенаправления на адрес сервера ACS. Не используется при платежах, не требующих дополнительной аутентификации на ACS Банка-эмитента. |
|
AN..512 | Нет |
Запрос аутентификации плательщика. Не используется при платежах, не требующих дополнительной аутентификации на ACS Банка-эмитента. |
Коды ошибок
Код ошибки | Текст ошибки |
---|---|
0 | Обработка запроса прошла без системных ошибок |
5 | Доступ запрещён |
5 | Пользователь должен изменить свой пароль |
5 | Исчерпаны попытки оплаты или закончилось время сессии |
5 | Ошибка валидации данных |
7 | Системная ошибка |
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant"> </soapenv:Header> <soapenv:Body> <mer:paymentOrder> <order orderId="17155e15-34c3-7578-8be7-9d6800096352" cardholderName="NO card" language="RU" seToken="Cfqv4t2XHBb9k8ixM7jxxCvziETS4koa3bV3F0QUvGVY47nKyMBqjGzV/rvmCAw6KzwoBDzeLsqwBLEzvQhaF627ZS0OJnhttBi4fL3/h/sBSwFtxr3s+oVUeoE3e4SNVUq9vciinOyNCIKqfpeQya+pOUYt3MgrtSeu66Ar12XEj4k6lecZN7Ffquj9RqhZsYhP63np5VCxJR90cNQG+TMWIFU6rqxLAe4gzCJtcXNrPT8aDOI201Zwd+e4K1YnrI7dZGlibO7MVMPB9m7NJaJTHko/MiJNWumAjS4yDDovLraIKMwOFTvAhqXsHslthpcUO0GZXEIaDRgERD7+jw=="> </order> </mer:paymentOrder> </soapenv:Body> </soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns1:paymentOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant"> <return info="Ваш платёж обработан, происходит переадресация..." redirect="https://ya.ru?orderId=b94eac90-e487-796a-8ed2-cf5a00096352&lang=ru" errorCode="0"/> </ns1:paymentOrderResponse> </soap:Body> </soap:Envelope>
Если для проведения платежа требуется применение технологии 3-D Secure, то после получения ответа на запрос оплаты клиента необходимо перенаправить на ACS. Существует два способа перенаправления: обычный и упрощённый (см. таблицу ниже).
Способ перенаправления | Описание | |
---|---|---|
Обычный |
Для перенаправления на ACS, мерчант со своей стороны должен отправить клиента по адресу, указанному в параметре acsUrl с телом запроса
Запрос должен быть в формате POST. В зависимости от используемой схемы подключения клиент после аутентификации на ACS будет перенаправлен в платёжный шлюз или в магазин. Процессы завершения платежа для каждого из этих случаев описаны ниже. |
|
Упрощённый |
Чтобы клиент попал на страницу ACS, продавец перенаправляет его на страницу платёжного шлюза следующего вида: |
В случае неверной попытки оплаты шлюз возвращает следующий ответ.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns1:paymentOrderResponse xmlns:ns1="http://server/webservices/merchant"> <return info="Операция отклонена. Проверьте введенные данные, достаточность средств на карте и повторите операцию." redirect="https://yandex.ru?orderId=39f1f59f-1836-7195-8452-1f6900003ad4&lang=ru" errorCode="0"/> </ns1:paymentOrderResponse> </soap:Body> </soap:Envelope>
В качестве URL-адреса перенаправления указывается значение, переданное в параметре failUrl
(или returnUrl
, если failUrl
отсутствует).
В случае исчерпания попыток оплаты шлюз возвращает следующий ответ.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns1:paymentOrderResponse xmlns:ns1="http://engine.server.ru/webservices/merchant"> <return errorCode="5" errorMessage="Исчерпаны попытки оплаты или закончилось время сессии"/> </ns1:paymentOrderResponse> </soap:Body> </soap:Envelope>
Возврат с ACS в шлюз. Классическая схема
ACS эмитента проводит аутентификацию держателя карты и перенаправляет клиента в платежный шлюз, передавая PARes. Платежный шлюз проводит авторизацию заказа при успешной аутентификации клиента на ACS, или отклоняет предавторизацию при неуспешной аутентификации клиента на ACS.
Возврат с ACS в магазин. Схема с использованием дополнительного метода Finish 3DS
ACS эмитента проводит аутентификацию держателя карты и перенаправляет клиента в обратно в магазин. Полученный от ACS PARes передается в магазин, после чего магазин передает его в шлюз при помощи метода finishThreeDS
.
Описание метода finishThreeDS
приведено ниже.
Параметры запроса:
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
AN..30 | Да |
Номер заказа, полученный при регистрации заказа. |
|
ANS | Да |
Ответ на запрос аутентификации плательщика. |
Параметры ответа:
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
ANS..512 | Да |
Адрес, на который требуется перенаправить пользователя в случае успешной оплаты, а также в случае неуспешной оплаты (при отсутствии переданного параметра Адрес нельзя указывать относительным путем, т.е. они не должны начинаться на «.» и «/». В противном случае вернется ошибка 4: «URL возврата некорректен». Например:
|
|
N..2 | Нет |
Код ошибки. |
|
|
Нет |
|
Если errorCode=0
и info=«Your order is proceeded, redirecting»
– оплата прошла успешно. В других случаях с ошибкой, см. сообщение об ошибке errorMessage
.
Коды ошибок (поле errorCode
):
Код ошибки | Текст ошибки |
---|---|
0 | Обработка запроса прошла без системных ошибок |
5 | Доступ запрещён |
5 | Пользователь должен изменить свой пароль |
7 | Заказ не найден |
7 | Системная ошибка |
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant"> <soapenv:Header/> <soapenv:Body> <mer:finishThreeDs> <request language="ru" md="8b5b7ee5-eb5a-4cf4-81ec-7153f7ca2864" paRes="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"/> </mer:finishThreeDs> </soapenv:Body> </soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns1:finishThreeDsResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant"> <return errorCode="0" returnUrl="http://ya.ru?orderId=8b5b7ee5-eb5a-4cf4-81ec-7153f7ca2864"/> </ns1:finishThreeDsResponse> </soap:Body> </soap:Envelope>
6. Требования к безопасности по PCI DSS
В документации PCI DSS, использование криптограммы рассматривается как «E-commerce merchants who outsource all payment processing to PCI DSS validated third parties, and who have a website(s) that doesn’t directly receive cardholder data but that can impact the security of the payment transaction. No electronic storage, processing, or transmission of any cardholder data on the merchant’s systems or premises.», то есть обработка платежных данных выполняется третьей стороной, но сайт влияет на безопасность карточных данных.
Для соблюдения требований стандарта, ТСП необходимо заполнять лист самооценки SAQ-EP и ежеквартально проходить ASV тестирование.
Документ можно изучить здесь.