Open Banking in Estonia

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

Схема работы

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

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

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

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

Проведение оплат с использованием метода 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"
  }
}

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

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

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

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

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

   • 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-библиотеку провайдера и вызова функции перенаправления к сервису провайдера, созданные с использованием данных из примера выше.

<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'
    }
); 

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

Для оповещений о результатах оплат с применением метода 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, в том числе с помощью аналитических панелей на вкладке Analytics.

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

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

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