Инструменты страницы
Алгоритм создания запроса оплаты
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.do с указанием seToken
Запрос оплаты заказа (paymentOrder.do 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.
Параметры запроса:
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
AN..30 | Да |
Логин служебной учётной записи продавца. |
|
AN..200 | Да |
Пароль служебной учётной записи продавца. |
MDORDER |
ANS..36 | Да |
Номер заказа в платёжном шлюзе. Уникален в пределах платёжного шлюза. |
|
AN..8192 | Нет | Шифрованное значение платежных данных, введённых клиентом на стороне ТСП.
В запросе необходимо передать либо seToken, либо параметры $PAN, $CVC, YYYY, MM и TEXT. |
$PAN |
N12…19 | Да |
Номер платёжной карты. При указании в запросе параметра seToken этот параметр не обязателен к передаче. |
$CVC |
N3 | Да |
Код CVC/CVV2 на обратной стороне карты. При указании в запросе параметра seToken этот параметр не обязателен к передаче. |
YYYY | N4 | Да | Год истечения срока действия карты.
При указании в запросе параметра seToken этот параметр не обязателен к передаче. |
MM | N2 | Да | Месяц истечения срока действия карты.
При указании в запросе параметра seToken этот параметр не обязателен к передаче. |
TEXT | A..512 | Да |
Имя держателя карты латиницей, если доступно. Длина поля ограничена 26 символами (латинские буквы, точка, пробел). При указании в запросе параметра seToken этот параметр не обязателен к передаче. |
|
A2 | Да |
Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию. |
|
ANS..39 | Нет |
IP-адрес покупателя. IPv6 поддерживается во всех запросах (до 39 символов). |
|
ANS..40 | Нет |
Адрес электронной почты покупателя. |
|
булеан | Нет |
Возможные значения:
|
|
Строка | Нет |
Дополнительные параметры запроса. Формат вида: {«Имя1»: «Значение1», «Имя2»: «Значение2»}. При указании «showLoyalty»:«false» взаимодействие с сервисом лояльности осуществляться не будет. В параметре запрещено передавать зарезервированные имена (в случае их передачи заказ может быть отклонен):
|
|
См. описание | Нет |
Блок 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 Банка-эмитента. |
|
AN..512 | Нет |
Адрес перенаправления на адрес сервера ACS. Не используется при платежах, не требующих дополнительной аутентификации на ACS Банка-эмитента. |
|
AN..512 | Нет |
Запрос аутентификации плательщика. Не используется при платежах, не требующих дополнительной аутентификации на ACS Банка-эмитента. |
Коды ошибок
Код ошибки | Текст ошибки |
---|---|
0 | Обработка запроса прошла без системных ошибок |
5 | Использованы все попытки оплаты |
5 | Системная или внутренняя ошибка |
Пример запроса:
https://all.test.com/payment/rest/paymentorder.do?userName=Vmerch-api&password=testPwd&MDORDER=5729932e-ad4f-7089-9acf-9ae900096352&TEXT=CardMOLDERU&language=ru&seToken=Cfqv4t2XHBb9k8ixM7jxxCvziETS4koa3bV3F0QUvGVY47nKyMBqjGzV%2FrvmCAw6KzwoBDzeLsqwBLEzvQhaF627ZS0OJnhttBi4fL3%2Fh%2FsBSwFtxr3s%2BoVUeoE3e4SNVUq9vciinOyNCIKqfpeQya%2BpOUYt3MgrtSeu66Ar12XEj4k6lecZN7Ffquj9RqhZsYhP63np5VCxJR90cNQG%2BTMWIFU6rqxLAe4gzCJtcXNrPT8aDOI201Zwd%2Be4K1YnrI7dZGlibO7MVMPB9m7NJaJTHko%2FMiJNWumAjS4yDDovLraIKMwOFTvAhqXsHslthpcUO0GZXEIaDRgERD7%2Bjw%3D%3D
Пример ответа:
{"redirect":"https://all.test.com/payment/merchants/rbs/finish.html?orderId=b94eac90-e487-796a-8ed2-cf5a00096352&lang=ru","info":"Ваш платёж обработан, происходит переадресация...","errorCode":0}
Если для проведения платежа требуется применение технологии 3-D Secure, то после получения ответа на запрос оплаты клиента необходимо перенаправить на ACS. Существует два способа перенаправления: обычный и упрощённый (см. таблицу ниже).
Способ перенаправления | Описание | |
---|---|---|
Обычный |
Для перенаправления на ACS, мерчант со своей стороны должен отправить клиента по адресу, указанному в параметре acsUrl с телом запроса
Запрос должен быть в формате POST. В зависимости от используемой схемы подключения клиент после аутентификации на ACS будет перенаправлен в платёжный шлюз или в магазин. Процессы завершения платежа для каждого из этих случаев описаны ниже. |
|
Упрощённый |
Чтобы клиент попал на страницу ACS, продавец перенаправляет его на страницу платёжного шлюза следующего вида: |
Если попытки оплаты заказа исчерпаны, то на последнюю попытку оплаты шлюз возвращает следующий ответ.
{"redirect":"false.html?login=test&orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1&lang=ru","info":"Операция отклонена. Проверьте введенные данные, достаточность средств на карте и повторите операцию.<br>Происходит переадресация...","errorCode":0}
В качестве URL-адреса перенаправления указывается значение, переданное в параметре failUrl
(или returnUrl
, если failUrl
отсутствует).
На все последующие попытки оплаты платёжный шлюз вернёт следующий ответ.
{"redirect":"false.html?login=test&orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1&lang=ru","info":"Происходит переадресация...","errorCode":0}
В качестве URL-адреса перенаправления указывается значение, переданное в параметре failUrl
(или returnUrl
, если failUrl
отсутствует).
При этом шлюз не будет возвращать ошибку.
Возврат с ACS в шлюз. Классическая схема
ACS эмитента проводит аутентификацию держателя карты и перенаправляет клиента в платежный шлюз, передавая PARes. Платежный шлюз проводит авторизацию заказа при успешной аутентификации клиента на ACS, или отклоняет предавторизацию при неуспешной аутентификации клиента на ACS.
Возврат с ACS в магазин. Схема с использованием дополнительного метода Finish 3DS
ACS эмитента проводит аутентификацию держателя карты и перенаправляет клиента в обратно в магазин. Полученный от ACS PARes передается в магазин, после чего магазин передает его в шлюз при помощи метода finish3dsPayment.do
.
Описание метода finish3dsPayment.do
приведено ниже.
Параметры запроса:
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
AN..30 | Да |
Логин служебной учётной записи продавца. |
|
AN..200 | Да |
Пароль служебной учётной записи продавца. |
|
ANS..36 | Да |
Номер заказа в платёжном шлюзе. Уникален в пределах платёжного шлюза. |
|
ANS | Да |
Ответ на запрос аутентификации плательщика. |
Параметры ответа:
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
ANS..* | Нет |
При успешном ответе. В случае платежа без необходимости аутентификации на ACS – URL, на который производится переадресация после платежа. В случае 3DS-платежа – URL для возврата с ACS. |
|
N..2 | Нет |
Код ошибки. |
|
AN..512 | Нет |
Сообщение об ошибке (при ответе с ошибкой). |
Если errorCode
= 0 - оплата прошла успешно. В других случаях с ошибкой, см. сообщение об ошибке error
.
Коды ошибок (поле errorCode
):
Код ошибки | Текст ошибки |
---|---|
0 | Обработка запроса прошла без системных ошибок |
5 | Доступ запрещён |
5 | Пользователь должен изменить свой пароль |
7 | Заказ не найден |
7 | Системная ошибка |
Пример запроса:
mdOrder=906bf262-bd53-4ac7-983c-07127954681b& paRes=eJzFV2uTokoS%2FSsTcz8aPYCC6A3HiOKNCshT8BtCyRuUN%2Fz6RXu6p%2B9s78bsbtxYIgyLE5VJnso8%0D%0AlVUb IywhZHToNSXcbiRYVW4Av0T%2B969ZFXzDvm43R6DB6on4qwW%2Bdq%2FwhVi58AVfXvAXlySWL95l%0D%0AQULU8yD0HwYtLK uoyLfYN%2FTbfIO8vU7OSy9083q7cb07JcpbfE4uUXSD%2FHjdZLAUmS25QV4HG%2BSn%0D%0AxbF5jKopxD7ytxIDutcfOypG MigGi8mj2Mlj8n2DPGZsfLeG2zmK4SiBEl%2Bw5Z%2Fo8k9siuaJb24P%0D%0AdyArmsn3nEDRRxQfsc20HCXMvWG7xBcb5P1t A%2FtbkcOH1QZ5H2%2BQn%2BHd3HyLfniw6Zl8T%2BjGsLeb%0D%0AOso%2BDeuJb6rarZtq62yQH6ON57btFgBAUQt%2FlELl vNechTSAt2ei%2B5yygV60RYkpqOn%2FaQXSoCij%0D%0AOsweof4V2CCPUJBnYrcbPQry6WMl%2FNJnaV59%2FxrW9e1PBOm6 7lu3%2BFaUATKfiCDoGpkm%2BFUU%2FPH1%0D%0A1Qr6Yn4t%2FiMz2s2LPPLcNBrdeqoKCdZh4X95j%2B0zN4b28IQhGku%2F TK5ePAzPXx4IusCIySfyudMP%0D%0AzH7nK78GW1buSxW6j4JGfnG03WjwCh8VAb%2BYmvj96x%2B%2FqQwmCmBV%2FzfRvEXy 0cObP8tNG7hlvTHg%0D%0AZld%2BdR0XC5bRZ0wYBGuMX0TS9ze715kb5D38H9xeE%2FlhwV4nhqxy1zVg8vNYF6J7bIQ75sC3 1BX1%0D%0AvfnyZIdDwMh25uRqdQpmB%2FFgIVlIKGMHfIHB%2FQYfHIkQuagyA0JJOEij%2FEj267KDx4zB6cpEayhj%0D%0A 6JGjXBat9Pu51hZ3S7RqlaN3A4Pn%2BpAplzUteVK%2FNnftIfCCarw7pnsiLt3N6B2MtOSdkF%2BC7x%2BS%0D%0A9IPlHg6v rGwCXTNu7b6OaFjW0XWqlmkfkESRLgyaBsE9AJ1IgUDcgWPO6SN0oll6kQDK0%2Fqd18XL%0D%0AglFZilJNILGgp0ewowLZoo BjgNQyJA10TOAwlqru2c5nHHsXnnlulNSuo1%2FxA9vJqm6pPWuA46ut%0D%0AZNACdfNpbLjM16hE4TZjsKjESJ0cA1QazV7i igkTn5g0vmOdyrAHCSQ8wEyWCiXasqSeZYDy6rcw%0D%0AKFQOvYxLHFvqGQbsX%2FHKABi1sxhWk8DqaQt6SfT4FD3Yu%2Fay ULvgvOoY1dnti7MYtp4MnpzBRA0F%0D%0AksjvQMFTYM%2BTfuSWjBpgpBln7c6tBE6PT%2BHRv6yR9c0%2Btyewb7x1d7%2FH zCJvzWU3a3a1I3J3GW9t%0D%0AehYnJExwiyPjNmG4hYai11xIl51iNddRTTlAzlT7djIkvrosh6ELbamzLp6yajDc4y2knxEW 7BIj%0D%0AKC3tcj%2Bnii1mME3l9oRdqx0hRLp1FVZwSEEgUQDwceCKT26COuVCQxWKclhOThaLcK1iFH%2BNCrLp%0D%0A9z Kcp46PCc1OEsBjfXyx024SD8G%2Fm1uYeqLGUzbVqqPVZ655tttZ5siqEsCf60yHkqDOucE5aaE3%0D%0AspI0LeQT7yXGZFNT 0tiO6Z62DNuFnWurtZetW1%2F8tR67Z1xsp3ISmLhd%2Fylf3Gu%2BWCDC87m21XtK%0D%0A7VHcnQdRxicF4h7mzknSghDFB2 M%2FiztSSXaIefIBFpArc5cQSGns1nOCXEcFUVbZQbCtWXPylqdy%0D%0AKXIKDq59pLYz%2FoQcJXV1a%2FB1sYLtejBaxy2q lX3ER99UcK2yqW5dOlqjH3GlndfKfn8sMmV3cC86%0D%0AMVVfShdNQpI40hvsJN5flfmpVPPxIdXop1SnKucREQpdvf5%2FSl VmnFHG%2FirVH1h3jP8nqR4fvH5I%0D%0AlX9K9SSHkxSvv%2FIFE9%2Bp2mTA0FSkTm5URl91ScOZHJ64buTqh5lGLC03GbFm 6jwOd0fYwt6NB71D%0D%0AQe2eVhgUGjoc4Iq0A4Y%2F2g1g6eKy17BbQcZZ1pIylt2LtPcPdQ0KYi%2BWpzVU5OUMmS10vBaT Zl%2Fe%0D%0AZ0vrYAy9TtQZKUzYwhICxW2c%2Bxl0Pt3r3F1suLhq4rCa2XbfdlRTEFUnMkAFVIHz0ZMb9eTsM4F6%0D%0Aoi hdhwoCbq2PiM6xCEEgYKLP6vIN2TNU91gvQZdY16DygDLO8hq%2FmrKq5fhdISs9tuvbSfA1MnI5%0D%0A9saKf9PWqdO0yhC9 WS0ysb2dxkmbj7g0iaUMMHETkM%2Fqc8oXBejaptC2TtGZapqtwKfFKrjTXRyH%0D%0AHXO4uXNLq1K3qfZ8vcJP6TGyUUOYU% 2Fc%2BQ8bsOFCxnDf2iRcyFd8HXHZ3UR1yGLgeEWcBTpDdgeWu%0D%0AgDGxynk0LJe0p1z6kp51QNKOjJgeBGVGYOoQ32RuLd CzZL689KZ7O1dz64TMb95xSWa1Kgx25Ki%2F%0D%0AJ1Nq9uiop%2F2bTE1pPbWOJqHtBp%2F5eXPwhjM77Bt8tQo%2B273%2B Hsm8S1btJ8nisgF6%2BdldWewXrBNj%0D%0Aduob%2BJsP28rS0dEpwxd24SXzU5G1pjaUDlCnlLPt%2FV7XFB2%2BVNG7tM%2 FpS2UkeKdTUd4J3HrG32v7%0D%0AeIgx2tnPdT%2FLmVpC1%2BMSdk17UOvMUwaubWoMoeZJo2p8CfXrCuHJS3XjclU9hXToTY e9DCACqpjl%0D%0APnKUgIpMkT7g0SGIjYt%2F5cANMjiXFDDDiOvcSpXVsrQKkpArgPX22WLQEsbKFQTUVTbat675WPOf%0D% 0AHYelkE6lJQD%2BZceRZX%2BJHI2BnN0DWd%2Bdg%2BqCCnmEEGrEqUrSoNJhQeAXWshEyYMhvuOQYbYGGuOL%0D%0AuhK6Mm 4oOrGcS6OD7KU0ETskYXSWu5SB2xP3qh1UJmKsBncxEd602JvfrYrq2LkLrd0Mk8hjnB%2FG%0D%0A7naxylHVT7rQOJ15iTUu XhZuMtic3BxPzTK7rDX0s46D%2FDwnIu9nx5%2Bnyud19Hk7ftyfPt6a%2FwFG%0D%0ADPms%0D%0A& userName=login&password=password
Пример ответа:
{"redirect":"http://ya.ru?orderId=906bf262-bd53-4ac7-983c-07127954681b","errorCode":0}
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 тестирование.
Документ можно изучить здесь.