Подключение с платежной страницей на стороне Магазина

1. Введение
2. Операции

• 2.1 Основные требования:
• 2.2 Этапы взаимодействия
• 2.3 EgoIframeReady - начало оплаты
• 2.4 Authorize - отправка данных карты
• 2.5 EgoIframeProcess - обработка
• 2.6 EgoIframe3ds - 3D SECURE аутентификация
• 2.7 EgoIframeResult - получение результатов
• 2.8 EgoIframeClose - завершение оплаты
• 2.9 EgoIframeError - сообщение об ошибке

3. Дополнительная информация

• 3.1 Пример исполняемого скрипта
• 3.2 Тестовые испытания
• 3.3 Сторонние справочные ресурсы
• 3.4 Ошибки

1. Введение

Назначение документа

Документ содержит техническое описание процесса передачи данных банковской карты для проведения авторизации платежа платежным шлюзом «МПС». Документ предназначен для технических специалистов Заказчика, которые отвечают за разработку сервиса оплаты банковскими картами в интернет-магазине Заказчика с использованием процессинговой системы MyPayments.

2. Операции

2.1 Основные требования:

Основные требования для работы по данному протоколу:

1. иметь представление о базовых запросах к сервисам платежного шлюза (далее ПШ);
2. иметь понимание работы клиентской части веб-приложений, в частности HTML5, JavaScript;
3. опыт работы с iframe, настройки общения между окнами, методом Window.postMessage

2.2 Этапы взаимодействия

Для организации приема банковской карты на своей стороне предприятие должно зарегистрировать заказ в системе, создать скрытый элемент iframe c адресом, который был получен при регистрации заказа. Дальнейшее взаимодействие между фреймами строится на базе функции HTML5 postMessage.

1. регистрация заказа в системе ПШ - используется стандартный протокол (например, метод register сервиса orderv2); взаимодействие происходит между сервисами ПШ и бэкэндом (server side) сайта/приложения Интернет точки продажи. Далее взаимодействие происходит между сервисами ПШ и фронтэндом (client side) сайта/приложения Интернет точки продажи;

2. создание скрытого элемента iframe с адресом, полученным в ответ на запрос из п.1; между итерфейсом ввода данных карты на сайте и iframe элементом включен механизм обмена сообщениями через postMessage.

3. взаимодействие с ПШ при помощи сообщений postMessage:

4. получить статус заказа в системе ПШ - используется стандартный протокол (например, метод get_by_order сервиса statusv2).

Более подробное описание сообщений дано ниже.

2.3 EgoIframeReady - начало оплаты

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

Данное сообщение не содержит дополнительной информации.

2.4 Authorize - отправка данных карты

После успешного ввода данных карты, сайт магазина отправляет сообщение Authorize со следующими параметрами в формате JSON:

• pan - полный номер карты или token;
• exp - дата истечения срока действия в форма YYYYMM;
• cvv - СVV2/CVC код.

Дополнительно могут быть переданы:

• holder - фамилия и имя держателя карты;
• phone - телефон держателя карты;
• email — адрес электронной почты держателя карты;
• save — признак необходимости «привязать» карту.

Важно: количество обязательных/опциональных полей зависит от выбранной схемы работы.

Пример авторизационной части запроса:

data = {
 'pan': '5100000000000008',
 'cvv': '222',
 'exp': '201912',
 'holder': 'Vasya Pupkin',
 'phone': '89119111213',
 'email': 'pupkin@vasya.ru'

};

2.5 EgoIframeProcess - обработка

Сообщение EgoIframeProcess направляется после успешного старта обработки переданных данных.

Данное сообщение не содержит дополнительной информации.

2.6 EgoIframe3ds - 3D SECURE аутентификация

Если предъявленная карта клиента участвует в программе 3D secure — необходимо выполнить процедуру аутентификации по технологии 3D secure. Для этого сайт заказчика должен отобразить iframe элемент, сразу после получения сообщения EgoIframe3ds из iframe. В “видимом” iframe элементе откроется страница банка-эмитента карты, на которой клиенту сайта необходимо ввести полученный одноразовый пароль.

Данное сообщение не содержит дополнительной информации.

2.7 EgoIframeResult - получение результатов

После завершения оплаты результаты отправляются сообщении EgoIframeResult в формате JSON следующего содержания:

• success – результат авторизации (может отсутствовать)
• comment – комментарий, к примеру ‘authorized successfully’
• status – статус оплаты
• repeat – возможность повторной оплаты (может отсутствовать)
• payments – платежи состоящие из:

- tdate – дата транзакции
- number – id платежа
- amount – сумма платежа
- currency – валюта платежа

Возможные результаты оплаты и соответствующие им статусы

Результат оплаты - “success”, если платежу присвоен один из следующих финальных статусов в системе ПШ:

Результат оплаты не “success”, если платежу присвоен один из следующих промежуточных статусов в системе ПШ:

Важно: более подробное описание статусов заказов содержится в основной документации, описывающей взаимодействие с платежным шлюзом.

Важно: если в процессе обработки возникла ошибка из iframe вернется сообщение EgoIframeError.

2.8 EgoIframeClose - завершение оплаты

По завершению оплаты из iframe отправляется сообщение EgoIframeClose, а URL в Iframe в соответствии с результатом оплаты меняется на success или fault адрес, указанные при регистрации заказа.

Данное сообщение не содержит дополнительной информации.

2.9 EgoIframeError - сообщение об ошибке

В случае возникновения ошибки, препятствующей проведению авторизации платежа, отправляется сообщение EgoIframeError в формате JSON следующего содержания:

• textStatus – код ошибки, к примеру ‘timeout’
• errorThrown – комментарий к ошибке, к примеру ‘system error’

3. Дополнительная информация

3.1 Пример исполняемого скрипта

<!DOCTYPE html>
<html>
<head>
  <title></title>
  <script src="http://code.jquery.com/jquery-1.8.3.js"></script>
  <script type="text/javascript" src="postmessage.js"></script>
<body>
<iframe id="iframe" src="https://sandbox.egopay.ru/payments/request?session=12321324341" frameborder="0" style="height:0;width:0;"></iframe>
<script type="text/javascript">

   $(document).ready(function(){
       if (window.pm) {
            window.pm.bind('EgoIframeReady', function() {
                console.log('EgoIframeReady');

                data = {
                    'pan':'5100000000000008',
                    'cvv':'222',
                    'exp': '201912',
                    'amt': 2850,
                    'cy': 'RUB',
                    'holder': 'Vasya Pupkin'
                };
                $.pm({
                    target: document.getElementById('iframe').contentWindow,
                    origin: "https://sandbox.egopay.ru",
                    url: "https://sandbox.egopay.ru",
                    type: 'Authorize', 
                    data: data,
                    success: function() {
                      console.log('ok');
                    },
                    error: function() {
                      console.log('error');
                    }
                }, "https://sandbox.egopay.ru");
                 console.log('sent autorize');
            });

            window.pm.bind('EgoIframeProcess', function() {
                console.log('payment process');
            });
            window.pm.bind('EgoIframe3ds', function() {
                console.log('EgoIframe3ds');
                $('#iframe').css({width: 500, height: 500})
            });
            window.pm.bind('EgoIframeResult', function() {
                console.log('EgoIframeResult', arguments);
            });
            window.pm.bind('EgoIframeClose', function() {
                console.log('EgoIframeClose', arguments);
            });
            window.pm.bind('EgoIframeError', function() {
                console.log('EgoIframeError', arguments);
            });
    }
});
</script> 
</body>
</html>

3.2 Тестовые испытания

Список обязательных тестовых сценариев приведен в таблице ниже

3.3 Сторонние справочные ресурсы

Общение между окнами: https://learn.javascript.ru/iframes http://javascript.ru/ajax/cross-origin-2

Метод Window.postMessage: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage

Метод Window.postMessage для устаревших браузеров - библиотека jQuery postMessage: https://github.com/daepark/postmessage

3.4 Ошибки