Open Banking in Estonia

Обзор

Open Banking in Estonia — метод интернет-банкинга для проведения платежей через банки Эстонии. Для работы с этим методом доступно проведение оплат через Payment Page и Gate.

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

Тип платёжного метода интернет-банкинг
Регионы использования EE
Валюты платежей EUR
Конвертация валют
Оплаты +
Выплаты
Оплаты по сохранённым данным
Полные возвраты
Частичные возвраты
Опротестования
Особенности
  • В зависимости от специфики провайдера, обрабатывающего платёж, при работе с методом Open Banking in Estonia может потребоваться дополнительное согласие пользователя на проведение платежа.
  • Поддерживается настройка вариантов отображения кнопок метода и банка на Payment Page.
Организация и стоимость подключения по согласованию с курирующим менеджером ECommPay

Схема работы

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



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

Интерфейсы Суммы, EUR
Payment Page CMS Plug-ins Gate Dashboard (Old Dashboard) Минимум Максимум
Оплаты + + * *

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

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

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

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

Проведение платежей с применением метода 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": "EUR"
  }
}
Табл. 1. Список банков
Банк ID
LHV bank 2111
Swedbank 2101
SEB bank 2091
COOP 22091
Citadele 5721

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

Оплаты через Payment Page

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

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

Проведение платежа выполняется с перенаправлением пользователя к сервису провайдера. В некоторых случаях пользователь может быть также перенаправлен к сервису выбранного банка для подтверждения платежа. Также следует учитывать, что, в зависимости от специфики провайдера, обрабатывающего платёж, при работе с этим методом для проведения оплаты может требоваться дополнительное согласие пользователя и, в некоторых случаях, дополнительные данные о пользователе. Для получения такого согласия и дополнительных сведений (когда они необходимы) на Payment Page отображается соответствующая страница.

Рис.: Схема проведения оплаты через Payment Page с перенаправлением пользователя к сервису провайдера



Рис.: Проведение оплаты через Payment Page с перенаправлением пользователя к сервису провайдера

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты передаётся к платёжной платформе.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. Осуществляется подготовка к открытию платёжной формы с учётом параметров вызова и свойств используемого проекта.
  6. Платёжная форма отображается пользователю.
  7. Пользователь выбирает платёжный метод Open Banking in Estonia и один из банков, поддерживающих работу с этим методом.
  8. Запрос на проведение оплаты через выбранный банк передаётся к платёжной платформе.
  9. На стороне платёжной платформы выполняется обработка запроса. При этом выявляется необходимость в получении дополнительного согласия пользователя и дополнительных данных о пользователе — с учётом специфики провайдера, через которого требуется провести платёж. Если необходимо получить такое согласие (и данные), выполняются следующие шаги:
    • От платёжной платформы к Payment Page направляется информация о необходимости получения согласия пользователя на проведение оплаты и, если необходимо, дополнительных данных, требуемых для проведения платежа.
    • На Payment Page пользователю отображается страница с уведомлением о необходимости подтвердить проведение оплаты и полями, которые необходимо заполнить для продолжения платежа.
    • Пользователь предоставляет запрашиваемые данные, соглашается с указанной информацией и подтверждает проведение платежа.
    • От Payment Page к платёжной платформе направляется предоставленная пользователем информация.
    • На стороне платёжной платформы выполняется обработка полученной информации.
  10. От платёжной платформы к Payment Page передаются данные для перенаправления пользователя к сервису провайдера.
  11. Пользователь перенаправляется к сервису провайдера, где ему отображается платёжная инструкция.
  12. Пользователь выполняет необходимые действия для проведения оплаты.
  13. Запрос на проведение платежа передаётся от сервиса провайдера к сервису банка.
  14. На стороне сервиса банка выполняется обработка платежа.
  15. От сервиса банка к сервису провайдера направляется уведомление о результате оплаты.
  16. Информация о результате оплаты отображается пользователю на стороне сервиса провайдера.
  17. Пользователь перенаправляется к Payment Page.
  18. От сервиса провайдера к платёжной платформе направляется уведомление о результате оплаты.
  19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  20. От платёжной платформы к Payment Page направляется информация о результате проведения оплаты.
  21. Информация о результате оплаты отображается пользователю на Payment Page.

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



Рис.: Проведение оплаты через Payment Page с перенаправлением пользователя к сервису банка

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты передаётся к платёжной платформе.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. Осуществляется подготовка к открытию платёжной формы с учётом параметров вызова и свойств используемого проекта.
  6. Платёжная форма отображается пользователю.
  7. Пользователь выбирает платёжный метод Open Banking in Estonia и один из банков, поддерживающих работу с этим методом.
  8. Запрос на проведение оплаты через выбранный банк передаётся к платёжной платформе.
  9. На стороне платёжной платформы выполняется обработка запроса. При этом выявляется необходимость в получении дополнительного согласия пользователя и дополнительных данных о пользователе — с учётом специфики провайдера, через которого требуется провести платёж. Если необходимо получить такое согласие (и данные), выполняются следующие шаги:
    • От платёжной платформы к Payment Page направляется информация о необходимости получения согласия пользователя на проведение оплаты и, если необходимо, дополнительных данных, требуемых для проведения платежа.
    • На Payment Page пользователю отображается страница с уведомлением о необходимости подтвердить проведение оплаты и полями, которые необходимо заполнить для продолжения платежа.
    • Пользователь предоставляет запрашиваемые данные, соглашается с указанной информацией и подтверждает проведение платежа.
    • От Payment Page к платёжной платформе направляется предоставленная пользователем информация.
    • На стороне платёжной платформы выполняется обработка полученной информации.
  10. От платёжной платформы к Payment Page передаются данные для перенаправления пользователя к сервису провайдера.
  11. Пользователь перенаправляется к сервису провайдера, а затем — к сервису банка, где пользователю отображается платёжная инструкция.
  12. Пользователь выполняет необходимые действия для проведения оплаты.
  13. На стороне сервиса банка выполняется обработка платежа.
  14. Информация о результате оплаты отображается пользователю на стороне сервиса банка.
  15. Пользователь перенаправляется к Payment Page.
  16. От сервиса банка к сервису провайдера направляется уведомление о результате оплаты.
  17. Уведомление о результате оплаты передаётся от сервиса провайдера к платёжной платформе.
  18. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  19. От платёжной платформы к Payment Page направляется информация о результате проведения оплаты.
  20. Информация о результате оплаты отображается пользователю на 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. Дополнительно рекомендуется указывать имя и фамилию пользователя в параметрах customer_first_name и customer_last_name. Если параметры отсутствуют в запросе, на Payment Page пользователю отображаются поля для ввода недостающих значений. Подробнее об уточнении параметров — в разделе Дополнение информации о платеже.

    Также при выборе некоторых банков пользователю может потребоваться указать на Payment Page номер счёта (International Bank Account Number, IBAN), в то время как при работе с другими банками номер счёта указывается пользователем уже на стороне провайдера. В силу специфики метода этот номер может указываться только пользователем и не может быть указан в запросах.

  4. Если при проведении платежей необходимо получать дополнительное согласие пользователей, рекомендуется передавать в запросе параметр merchant_return_url с указанием URL для перенаправления пользователя к веб-сервису, чтобы в случае отказа от предоставления согласия пользователь мог вернуться к веб-сервису мерчанта, щёлкнув соответствующую кнопку в платёжной форме. При этом, во избежание повторного оформления заказа на стороне веб-сервиса, рекомендуется указать тот адрес, который ведёт на страницу подтверждения заказа.
  5. При использовании платёжного метода Open Banking in Estonia можно настраивать отображение страницы Payment Page с выбором метода оплаты.

    По умолчанию банки, поддерживающие проведение оплат методом Open Banking in Estonia, объединены в группу и отображаются одной кнопкой 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=="
          }
  6. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
  7. После определения всех параметров необходимо составить подпись. Подробнее — в разделе Работа с подписью к данным.

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

    { 
      payment_id: 'X03936', 
      payment_amount: 1000, 
      payment_currency: 'EUR',
      customer_id: 'customer1',
      project_id: 123,
      customer_first_name: 'John',
      customer_last_name: 'Doe',
      merchant_return_url: 'http://example.com/return',
      signature: "kUi2x9dKHAVNU0FYldJrxh4...zUCwX6R\/ekpZhkIQg=="
    }

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

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

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

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

{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "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": "abc67890",
            "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

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

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

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

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

Рис.: Схема проведения оплаты через Gate с перенаправлением пользователя к сервису провайдера



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

  1. Пользователь на стороне веб-сервиса инициирует оплату через один из банков, поддерживающих работу с методом Open Banking in Estonia.
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
  6. На стороне платёжной платформы выполняется дальнейшая обработка запроса. При этом выявляется необходимость в получении дополнительного согласия пользователя и дополнительных данных о пользователе — с учётом специфики провайдера, через которого требуется провести платёж. Если необходимо получить такое согласие (и данные), выполняются следующие шаги:
    • От платёжной платформы к веб-сервису направляется информация о необходимости получения согласия пользователя на проведение оплаты и, если необходимо, дополнительных данных, требуемых для проведения платежа.
    • На стороне веб-сервиса запрашивается согласие пользователя на проведение платежа и предоставление пользователем дополнительных данных, которые необходимы для продолжения платежа.
    • Пользователь предоставляет запрашиваемые данные, соглашается с указанной информацией и подтверждает проведение платежа.
    • От веб-сервиса к платёжной платформе направляется предоставленная пользователем информация.
    • На стороне платёжной платформы выполняется обработка полученной информации.
  7. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера.
  8. Пользователь перенаправляется к сервису провайдера, где пользователю отображается платёжная инструкция.
  9. Пользователь выполняет необходимые действия для проведения оплаты.
  10. Запрос на проведение оплаты передаётся от сервиса провайдера к сервису банка.
  11. На стороне сервиса банка выполняется обработка платежа.
  12. От сервиса банка к сервису провайдера направляется уведомление о результате оплаты.
  13. Информация о результате оплаты отображается пользователю на стороне сервиса провайдера.
  14. Пользователь перенаправляется к веб-сервису мерчанта.
  15. От сервиса провайдера к платёжной платформе направляется уведомление о результате оплаты.
  16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  17. От веб-сервиса пользователю направляется информация о результате оплаты.

Рис.: Схема проведения оплаты через Gate с перенаправлением пользователя к сервису банка



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

  1. Пользователь на стороне веб-сервиса инициирует оплату через один из банков, поддерживающих работу с методом Open Banking in Estonia.
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
  6. На стороне платёжной платформы выполняется дальнейшая обработка запроса. При этом выявляется необходимость в получении дополнительного согласия пользователя и дополнительных данных о пользователе — с учётом специфики провайдера, через которого требуется провести платёж. Если необходимо получить такое согласие (и данные), выполняются следующие шаги:
    • От платёжной платформы к веб-сервису направляется информация о необходимости получения согласия пользователя на проведение оплаты и, если необходимо, дополнительных данных, требуемых для проведения платежа.
    • На стороне веб-сервиса запрашивается согласие пользователя на проведение платежа и предоставление пользователем дополнительных данных, которые необходимы для продолжения платежа.
    • Пользователь предоставляет запрашиваемые данные, соглашается с указанной информацией и подтверждает проведение платежа.
    • От веб-сервиса к платёжной платформе направляется предоставленная пользователем информация.
    • На стороне платёжной платформы выполняется обработка полученной информации.
  7. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера.
  8. Пользователь перенаправляется к сервису провайдера, а затем — к сервису банка, где пользователю отображается платёжная инструкция.
  9. Пользователю отображается страница оплаты, и пользователь выполняет необходимые действия для проведения оплаты.
  10. На стороне сервиса банка выполняется обработка платежа.
  11. Информация о результате оплаты отображается пользователю на стороне сервиса банка.
  12. Пользователь перенаправляется к веб-сервису мерчанта.
  13. От сервиса банка к сервису провайдера направляется уведомление о результате оплаты.
  14. От сервиса провайдера к платёжной платформе направляется уведомление о результате оплаты.
  15. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  16. От веб-сервиса пользователю направляется информация о результате оплаты.

Информация о формате запросов и параметрах инициирования оплат через 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. Дополнительно рекомендуется указывать имя и фамилию пользователя. Если параметры отсутствуют в запросе, список недостающих параметров отправляется в оповещении на уточнение. Подробнее об уточнении параметров — в разделе Дополнение информации о платеже.

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

    • customer — объект, содержащий сведения о пользователе:
      • first_name — имя,
      • last_name — фамилия.
    Также при выборе некоторых банков может потребоваться номер счёта пользователя (International Bank Account Number, IBAN), в то время как при работе с другими банками этот номер указывается пользователем на стороне провайдера. В случаях, когда необходимо указать номер счёта до перенаправления пользователя к сервису провайдера, в оповещении на уточнение указывается параметр number объекта account; и если в исходном запросе не были указаны параметры first_name и last_name объекта customer, то все эти три параметра указываются в одном оповещении на уточнение. В силу специфики метода, если номер счёта пользователя указывается в исходном запросе, он не учитывается при первичной обработке этого запроса, и может быть указан либо на стороне веб-сервиса после получения оповещения на уточнение, либо на стороне провайдера после перенаправления пользователя.
  4. Валютой платежа может быть только EUR.
  5. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода 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",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 140
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}

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

При работе с методом Open Banking in Estonia, в зависимости от специфики провайдера, может потребоваться получать дополнительное согласие пользователей на проведение платежей с использованием этого метода. Для проведения платежа с учётом согласия пользователя со стороны веб-сервиса необходимо:

  1. Принять от платёжной платформы оповещение о необходимости получения согласия пользователя (и дополнения информации о платеже, если это необходимо).
  2. Получить от пользователя это согласие (и дополнительные сведения, если это необходимо).
  3. Передать информацию о согласии пользователя (и дополнительные сведения, если это необходимо) в запросе в платёжную платформу.

В оповещении от платёжной платформы в параметре clarification_fields.customer.properties.psu_consent_text.default содержится текст, который необходимо отобразить пользователю для получения его согласия на проведение платежа.

Далее приведён фрагмент оповещения о необходимости получения согласия пользователя.

{
    "clarification_fields": {
        "customer": {
            "type": "object",
            "description": "",
            "properties": {
                "psu_consent": {
                    "type": "string",
                    "description": "Need to request the users consent to make a payment"
                 },
                "psu_consent_text": {
                    "type": "string",
                    "description": "The text to be displayed on the payment form",
                    "default": "=== The PSU consent text to be displayed on payment page ==="  
}

Запрос на продолжение платежа с учётом согласия пользователя (и дополнительных сведений, если это необходимо) отправляется методом POST к конечной точке /v2/payment/clarification и должен содержать следующие объекты и параметры:

  • general — объект, содержащий основные идентификационные сведения запроса:
    • project_id — идентификатор проекта, к которому относится проводимый платёж.
    • payment_id — идентификатор платежа, к которому относятся отправляемые данные.
    • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным).
  • additional_data — объект с информацией о согласии пользователя на проведение платежа (и дополнительными сведениями, если они необходимы):
    • customer — объект, содержащий сведения о пользователе:
      • psu_consent — информация о получении согласия пользователя на проведение оплаты. Если пользователь дал согласие на проведение платежа, необходимо передать значение 1; если указать иное значение, согласие на проведение платежа запрашивается повторно.
      • psu_consent_text — текст запроса согласия пользователя на проведение оплаты, который был отображён пользователю. В значении этого параметра должен передаваться именно тот текст, который был получен в оповещении о необходимости получения согласия пользователя. Если текст, указанный в запросе, отличается от текста, полученного в оповещении, согласие на проведение платежа запрашивается повторно.

Вместе с информацией о согласии в запросе на продолжение платежа может потребоваться указать дополнительные данные о пользователе, приведённые в разделе Формат запросов.

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

{
    "general": {
        "project_id": 10571,
        "payment_id": "1234567890",
        "signature": "=== signature ==="
    },
    "additional_data": {
        "customer": {
            "psu_consent": "1",
            "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
            "first_name": "Firstname",
            "last_name": "Lastname"
        "account": {
            "number": "AB123456789"
        }
    }
}

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

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

Вариант 1

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

  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": "EE",
            "callback_url": "https://callback.url.org"
    }
  }

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

Рис.: Пример ссылки на 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':'EE',
    'callback_url':'https://callback.url.org'
    }
); 

Вариант 2

Для перенаправления пользователя от веб-сервиса на сайт сервиса Open Banking in Estonia необходимо принять оповещение от платёжной платформы, содержащее ссылку для перенаправления в параметре redirect_data.url и данные для отправки в теле запроса redirect_data.body, и использовать эти параметры при открытии HTML-страницы сайта методом, указанным в redirect_data.method.

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

  "redirect": {
        "method": "POST",
        "encrypted": [],
        "url": "https://web-app.example.com/app/request-token/rq:3R123"
    }

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

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

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

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

{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "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": "abc67890",
            "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.