Open Banking in Estonia

Характеристика

Схема работы

В проведении отдельного платежа с использованием метода Open Banking in Estonia задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ECommPay, а также сервис одного из банков, поддерживающих работу с этим методом.

Основные операции

* Ограничения сумм платежей зависят от банков.

Сценарии использования

Проведение оплат с использованием метода Open Banking in Estonia выполняется с перенаправлением пользователей на сайт провайдера.

Рис.: Оплата через Payment Page с выбором банка на стороне Payment Page

Рис.: Оплата через Payment Page с выбором банка на стороне провайдера

Рис.: Оплата через Gate с выбором банка на стороне веб-сервиса

Рис.: Оплата через Gate с выбором банка на стороне провайдера

Поддержка со стороны банков

Проведение платежей с применением метода Open Banking in Estonia осуществляется через банки, поддерживающие работу с этим методом. Банкам соответствуют свои идентификаторы, которые используются при инициировании оплат через Gate, а также при вызове Payment Page для отображения страницы с выбором метода оплаты.

Далее в таблице в ознакомительных целях представлена информация об этих банках, которую следует уточнять у курирующего менеджера ECommPay или по запросу /v2/info/banks/estonia/sale/list отправляемому методом POST через Gate API и относящемуся к группе запросов /v2/info/banks/{payment_method}/{operationType}/list.

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

{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "supported currency code (i.e. USD)"
  }
}

Общая информация

Для оплаты через Payment Page с использованием метода Open Banking in Estonia со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате оплаты. При этом метод Open Banking in Estonia можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платежного метода).

Доступны два способа выбора банка: на стороне Payment Page или на стороне провайдера.

Рис.: Схема проведения оплаты с выбором банка на Payment Page

Рис.: Схема проведения оплаты с выбором банка на стороне провайдера

Информация о формате запросов и параметрах вызова Payment Page при работе с методом Open Banking in Estonia, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API — в разделе Описание Payment Page API.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода Open Banking in Estonia необходимо учитывать следующее:

1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
   • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_amount — сумма платежа в минорных единицах валюты;
   • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
   • customer_id — идентификатор пользователя уникальный в рамках проекта.
2. Валютой платежа может быть только EUR.

3. При использовании платёжного метода Open Banking in Estonia можно настраивать отображение страницы Payment Page с выбором метода оплаты.

   По умолчанию банки, поддерживающие проведение оплат методом Open Banking in Estonia, объединены в группу и отображаются одной кнопкой Open Banking in Estonia, поэтому выбор банка осуществляется в два этапа.

   Оплата через Payment Page с выбором банка на стороне сервиса провайдера

   При использовании платёжного метода Open Banking in Estonia с выбором банка на стороне сервиса провайдера сначала выбирается метод Open Banking in Estonia на Payment Page, а затем выполняется выбор конкретного банка на стороне сервиса провайдера. В данном случае можно настраивать отображение Payment Page с предварительно выбранным платёжным методом Open Banking in Estonia. Для этого необходимо передать код estonia в параметре force_payment_method.

   Оплата через Payment Page с выбором банка на стороне Payment Page

   При использовании платёжного метода Open Banking in Estonia с выбором банка на стороне Payment Page сначала выбирается метод Open Banking in Estonia среди прочих, а затем на следующей странице с перечнем банков выбирается конкретный банк. Существует несколько вариантов отображения страницы Payment Page с выбором метода оплаты:

   • Отображение каждого банка группы отдельной кнопкой. Для этого необходимо передавать параметр split_banks со значением true в строке payment_methods_options.

     payment_methods_options={"estonia": {"split_banks": true}}
     

   • Отображение кнопок конкретных банков (одного или нескольких). В списке методов может присутствовать метод Open Banking in Estonia. Для этого необходимо передавать идентификаторы банков в параметре banks_id. Для отображения нескольких банков необходимо перечислять идентификаторы этих банков через запятую c пробелом.

     payment_methods_options={"estonia": {"split_banks": true, "banks_id": [2111, 2101]}}

   • Отображение только банков группы без других методов. Для этого используется предварительный выбор метода Open Banking in Estonia. Необходимо передавать код платежного метода estonia в параметре force_payment_method. Пользователю открывается страница с выбором банков, минуя страницу с выбором метода оплаты.
   • Отображение предварительно выбранного банка на стороне провайдера. Для этого используется предварительный выбор метода Open Banking in Estonia. Необходимо передавать код платежного метода estonia в параметре force_payment_method и идентификатор банка banks_id в параметре payment_methods_options. Перенаправление пользователя на сайт провайдера осуществляется без подтверждения готовности оплатить, минуя страницы с выбором метода оплаты и с выбором банков.

     Рис.: Пример запроса на оплату с отображением выбранного банка на стороне провайдера

         {
           payment_id: 'X03936', 
           payment_amount: 1000, 
           payment_currency: 'EUR', 
           project_id: 123,
           customer_id: 'customer1',
           force_payment_method: 'estonia',
           payment_methods_options={"estonia": {"banks_id": [2111]}},
           signature: "kUi2x9dKHAVNU0FYlSCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
         }

4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
5. После определения всех параметров необходимо составить подпись. Подробнее — в разделе Работа с подписью к данным.

Таким образом, корректный запрос на открытие платёжной формы с применением метода Open Banking in Estonia должен содержать идентификатор, сумму и валюту платежа, идентификаторы проекта и пользователя, а также подпись:

    { 
      payment_id: 'X03936', 
      payment_amount: 1000, 
      payment_currency: 'EUR',
      customer_id: 'customer1',
      project_id: 123,
      signature: "kUi2x9dKHAVNU0FYldJrxh4...zUCwX6R\/ekpZhkIQg=="
    }

Формат оповещений

Для оповещений о результатах оплат с применением метода Open Banking in Estonia используется стандартный формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 была успешно проведена оплата в размере 10,00 EUR.

{
        "project_id": 200,
        "payment": {
            "id": "E2E_deploy_S05_0.04896200_1584714117",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Estonian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }

В следующем примере оплата была отклонена.

{
        "project_id": 200,
        "payment": {
            "id": "E2E_deploy_S05_0.04896200_1584714118",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Estonian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }

Дополнительные материалы

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация о выполнении операций

Общая информация

Для оплаты через Gate с использованием метода Open Banking in Estonia со стороны веб-сервиса необходимо:

1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay.
2. Осуществить перенаправление пользователя на сайт провайдера, поддерживающего работу с методом Open Banking in Estonia.
3. Принять оповещение о результате оплаты.

Полная схема проведения оплаты представлена далее.

Рис.: Проведение оплаты через Gate с выбором банка на стороне веб-сервиса

Рис.: Проведение оплаты через Gate с выбором банка на стороне провайдера

Информация о формате запросов и параметрах инициирования оплат через Gate при работе с методом Open Banking in Estonia, а также о форматах данных для перенаправления пользователей и о формате оповещений о результатах оплат приведена далее; общая информация о работе с API — в разделе Работа с API.

Формат запросов

При формировании запросов на оплату с применением метода Open Banking in Estonia необходимо учитывать следующее:

1. Должен использоваться запрос /v2/payment/banks/estonia/sale, отправляемый методом POST. Этот запрос относится к группе запросов /v2/payment/banks/{payment_method}/sale.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в минорных единицах валюты,
     • currency — валюта платежа в формате ISO-4217 alpha-3;
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор, уникальный в рамках проекта,
     • ip_address — используемый IP-адрес,
   • account — объект, содержащий сведения о банковском счёте пользователя:
     • bank_id — идентификатор банка; данный параметр не является обязательным при использовании способа выбора банка на стороне провайдера,
   • return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис:
     • return — URL для перенаправления пользователя по нажатию кнопки на любом шаге оплаты.
3. Валютой платежа может быть только EUR.
4. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода Open Banking in Estonia должен содержать идентификаторы проекта, пользователя и платежа, подпись, сумму и валюту платежа, информацию о пользователе, идентификатор банка и URL для перенаправления:

{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "1.2.3.4"
    },
    "account":{
      "bank_id": 140
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}

Форматы данных для перенаправления пользователей

Для перенаправления пользователя от веб-сервиса к сайту провайдера необходимо:

1. Принять от платёжной платформы оповещение с объектом redirect_data, содержащим в объекте body данные для подключения JavaScript-библиотеки провайдера и вызова функции перенаправления на сайт провайдера.
2. Подключить JavaScript-библиотеку провайдера, ссылка на которую указана в параметре widget_url объекта body.
3. Вызвать функцию перенаправления на сайт провайдера с использованием параметров, переданных в объекте body (в соответствии с требованиями провайдера).

В объекте body содержатся следующие обязательные параметры:

• widget_url — ссылка на JavaScript-библиотеку провайдера,
• widget_host — доменное имя сервера провайдера,
• token — токен, который необходимо использовать в data.token в функции перенаправления,
• other — определяет возможность оплаты через банки, которые не поддерживаются по умолчанию на стороне провайдера; в данной технической реализации эта возможность не поддерживается, в значении параметра всегда передаётся off,
• callback_url — URL для перенаправления пользователя к веб-сервису после оплаты;

Также в объекте body могут содержаться следующие необязательные параметры:

• creditor — банковский идентификационный код (БИК); используется при выборе банка на стороне веб-сервиса,
• css — ссылка на файл формата CSS со стилями, которые позволяют изменить мерчанту внешний вид сайта провайдера,
• default_country — код страны в формате ISO 3166-1 alpha-2, поддерживаемые банки которой по умолчанию отображаются на сайте провайдера после перенаправления.

  "redirect_data": {
    "url": "http://pay.test/example",
        "method": "POST",
    "body": {
      "widget_url":"https://psd2.neopay.lt/widget.js",
      "widget_host":"https://psd2.neopay.lt/",
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCIp0cnVlLCJpYXQiOjE0OTMyMD",
            "other": "off",
            "creditor": "EEUHEE2X",
            "css": "https://css.test.org",
            "default_country": "ES",
            "callback_url": "https://callback.url.org"
    }
  }

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

<script type="text/javascript" src="https://psd2.neopay.lt/widget.js"></script> 

var NEOWidgetHost = "https://psd2.neopay.lt";
NEOWidget.initialize(
    NEOWidgetHost,
    data.token,
    {
    'other':'off',
    'creditor': 'EEUHEE2X',
    'css':'https://css.test.org',
    'default_country':'ES',
    'callback_url':'https://callback.url.org'
    }
); 

Формат оповещений о результатах оплат

Для оповещений о результатах оплат с применением метода Open Banking in Estonia используется стандартный формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 была успешно проведена оплата в размере 10,00 EUR.

{
        "project_id": 200,
        "payment": {
            "id": "E2E_deploy_S05_0.04896200_1584714117",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Estonian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }

В следующем примере оплата была отклонена из-за нарушения ограничения на сумму.

{
        "project_id": 200,
        "payment": {
            "id": "E2E_deploy_S05_0.04896200_1584714118",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Estonian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация о выполнении операций

Как и при работе с другими платёжными методами, которые предоставляет ECommPay, при использовании метода Open Banking in Estonia доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

Всю необходимую информацию можно получать и анализировать средствами Dashboard (Old Dashboard), в том числе с помощью аналитических панелей на вкладке Analytics.

Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:

• Dashboard (Old Dashboard) позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
• Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ECommPay.