Open Banking in Poland
Обзор
Open Banking in Poland — метод интернет-банкинга с использованием открытых банковских протоколов и расширенными возможностями для защищённой работы с информацией о пользователях. Этот метод относится к группе Open Banking и позволяет проводить платежи в злотых через банки Польши.
В платёжной платформе ecommpay поддерживаются оплаты методом Open Banking in Poland. Вместе с тем, для проведения выплат, в том числе в целях возврата средств по проведённым оплатам, при работе с этим методом может использоваться комплементарный метод Выплаты на банковские счета в ЕЗПЕ (SEPA).
Характеристика
Тип платёжного метода | банковские платежи |
---|---|
Платёжные инструменты |
|
Регионы использования | PL |
Валюты платежей | PLN |
Конвертация валют | на стороне ecommpay |
Оплаты | + |
Выплаты | – |
Оплаты по сохранённым данным | – |
Полные возвраты | – |
Частичные возвраты | – |
Опротестования | – |
Особенности |
|
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием метода Open Banking in Poland задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также сервис одного из банков, поддерживающих работу с этим методом.
Основные операции
Интерфейсы | Суммы | Время ** | ||||||
---|---|---|---|---|---|---|---|---|
Payment Page | CMS Plug-ins | Gate | Dashboard | минимум | максимум | базовое | предельное | |
Оплаты | + | – | + | – | * | * | * | * |
* Ограничения сумм и время проведения платежей зависят от банков.
** Базовое и предельное время определяются следующим образом:
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.
Сценарии использования
Проведение оплат с использованием метода Open Banking in Poland выполняется с перенаправлением пользователей к сервису провайдера.
Поддержка со стороны банков
Платежи с применением метода Open Banking in Poland проводятся через поддерживающие этот метод банки. При работе через Payment Page, как правило, выбор банка осуществляется пользователем уже в платёжной форме, но при вызовах Payment Page с предварительным выбором метода и банка, а также при инициировании оплат через Gate банк должен быть выбран пользователем на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка.
Далее в таблице в ознакомительных целях приведены названия и идентификаторы банков, поддерживающих работу с методом Open Banking in Poland.
Банк | ID |
---|---|
Alior Bank | 22411 |
Bank Millennium | 22421 |
Bank Pekao | 22431 |
BNP Paribas | 55421 |
Credit Agricole | 22481 |
Idea Bank | 22521 |
ING Bank Slaski | 22531 |
Inteligo | 22541 |
mBank | 22551 |
Nest Bank | 22571 |
PKO Bank Polski | 22581 |
Santander Bank Polska | 22591 |
Поскольку состав доступных банков может меняться, для получения актуальной на конкретный момент информации рекомендуется использовать POST-запрос к конечной точке /v2/info/banks/poland/sale/list
, которая относится к группе конечных точек /v2/info/banks/{payment_method}/{operationType}/list
Gate API. В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений.
Рис.: Пример данных из запроса на получение списка банков
{ "general": { "project_id": 200, "payment_id": "ORDER_155860015", "signature": "K6jllym+PtObocZtr345st...==" }, "payment": { "amount": 1000, "currency": "PLN" } }
Рис.: Пример данных из ответа с информацией о банках
[ { "id": 22411, // Индентификатор банка "abbr": "ALIOR", // Служебная аббревиатура банка (для внутреннего применения) "name": "Alior Bank", // Основное название банка "nativeName": "Alior Bank", // Локальное название банка "currencies": [ // Массив с информацией о валютах, поддерживаемых банком { "id": 1140, // Идентификатор валюты в платёжной платформе "alpha_3_4217": "PLN", // Буквенный код валюты платежа в формате ISO-4217 alpha-3 "number_3_4217": "985", // Цифоровой код валюты платежа в формате ISO-4217 alpha-3 "exponent": 2 // Число дробных разрядов валюты } ] }, { "id": 22551, "abbr": "MBANK", "name": "mBank", "nativeName": "mBank", "currencies": [ { "id": 1140, "alpha_3_4217": "PLN", "number_3_4217": "985", "exponent": 2 } ] }, { "id": 22581, "abbr": "PKO-BANK-POLSKI", "name": "PKO Bank Polski", "nativeName": "PKO Bank Polski", "currencies": [ { "id": 1140, "alpha_3_4217": "PLN", "number_3_4217": "985", "exponent": 2 } ] } ]
С вопросами о работе с банками, поддерживающими метод Open Banking in Poland, можно обращаться к курирующему менеджеру ecommpay.
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.
Оплаты через Payment Page
Общая информация
Для оплаты через Payment Page с использованием метода Open Banking in Poland со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате оплаты. При этом метод Open Banking in Poland можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжных методов). Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Payment Page. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты передаётся к платёжной платформе.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- Осуществляется подготовка к открытию платёжной формы с учётом параметров вызова и свойств используемого проекта.
- Платёжная форма отображается пользователю.
- Пользователь выбирает платёжный метод Open Banking in Poland и один из банков, поддерживающих работу с этим методом.
- Запрос на проведение оплаты через выбранный банк передаётся к платёжной платформе.
- На стороне платёжной платформы выполняется обработка запроса.
- От платёжной платформы к Payment Page передаются данные для перенаправления пользователя к сервису провайдера.
- Пользователь перенаправляется к сервису провайдера, а затем — к сервису банка, где пользователю отображается платёжная инструкция.
- Пользователь выполняет необходимые действия для проведения оплаты.
- На стороне сервиса банка выполняется обработка платежа.
- Информация о результате оплаты отображается пользователю на стороне сервиса банка.
- Пользователь перенаправляется к Payment Page.
- От сервиса банка к сервису провайдера направляется уведомление о результате оплаты.
- Уведомление о результате оплаты передаётся от сервиса провайдера к платёжной платформе.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется информация о результате проведения оплаты.
- Информация о результате оплаты отображается пользователю на Payment Page.
Информация о формате запросов и параметрах вызова Payment Page при работе с Open Banking in Poland, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API представлена в разделе Описание Payment Page API.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода Open Banking in Poland необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_amount — сумма платежа в дробных единицах валюты;
- payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
- customer_id — идентификатор пользователя уникальный в рамках проекта.
- Для предварительного выбора группы методов Open Banking необходимо указывать код группы
openbanking
в параметреforce_payment_group
. -
Можно настраивать отображение страницы Payment Page с выбором метода оплаты.
По умолчанию названия банков, объединены в группу и отображаются одной кнопкой Polish banks, поэтому выбор банка осуществляется в два этапа. Сначала выбирается метод Polish banks среди прочих методов, а затем на следующей странице с перечнем банков выбирается конкретный банк. Существует несколько вариантов отображения страницы Payment Page с выбором метода оплаты:
- Отображение банков одной кнопкой Polish banks среди прочих методов.
- Отображение только поддерживаемых банков одной кнопкой Polish banks. Для этого используется предварительный выбор метода Open Banking in Poland. Необходимо передавать код платежного метода
online-polish-banks
в параметре force_payment_method. Пользователю сразу открывается страница с выбором банков. - Отображение банков отдельными кнопками среди прочих методов. Для этого необходимо передавать параметр split_banks со значением
true
в параметре payment_methods_options."payment_methods_options": "{\"online_polish_banks\": {\"split_banks\": true}}"
- Отображение кнопок конкретных банков (одного или нескольких). В списке методов может присутствовать метод Open Banking in Poland. Для этого используется предварительный выбор метода Open Banking in Poland, но с указанием конкретного банка. Для этого необходимо передавать код платежного метода
online-polish-banks
в параметре force_payment_method и идентификатор банка banks_id в параметре payment_methods_options. Для отображения нескольких банков необходимо перечислять идентификаторы этих банков через запятую c пробелом."payment_methods_options": "{\"online_polish_banks\": {\"split_banks\": true, \"banks_id\": [22411, 22421]}}"
Ниже приведён пример запроса на открытие Payment Page с предварительно выбранным банком.
Рис.: Пример запроса с предварительным выбором метода и банка
{ payment_id: '580', payment_amount: 1000, payment_currency: 'PLN', project_id: 120, force_payment_method: 'online-polish-banks', payment_methods_options: '{\"online_polish_banks\": {\"banks_id\": [22411]}}', customer_id: 'customer1', signature: "XFyr/D1zXj84lUZVfpbWZol9JAZLnUZoPJKPXRbOqBUpxxa/hOKm2 P8XOqydoyeIi7KdqrcxLFd3GxgPgUzIDg== }
- Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
- После определения всех параметров необходимо составить подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода Open Banking in Poland должен содержать идентификаторы проекта, пользователя и платежа, валюту и сумму платежа, а также подпись:
{ payment_id: 'X03936', payment_amount: 1000, payment_currency: 'PLN', project_id: 123, customer_id: 'customer1', signature: "kUi2x9dKHA...\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg==" }
Формат оповещений
Для оповещений о результатах оплат с применением метода Open Banking in Poland используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 239
была успешно проведена оплата в размере 10,00 PLN
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 239, "payment": { "id": "ABC12345", "type": "purchase", "status": "success", "date": "2020-11-03T14:41:38+0000", "method": "Polish Banks", "sum": { "amount": 1000, "currency": "PLN" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 77796010023511, "type": "sale", "status": "success", "date": "2020-11-03T14:41:38+0000", "created_date": "2020-11-03T14:39:34+0000", "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797", "sum_initial": { "amount": 1000, "currency": "PLN" }, "sum_converted": { "amount": 1000, "currency": "PLN" }, "code": "0", "message": "Success", "provider": { "id": 3901, "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf", "auth_code": "" } }, "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw==" }
В следующем примере оплата была отклонена.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 10801, "payment": { "id": "ABC67890", "type": "purchase", "status": "decline", "date": "2020-11-03T15:47:39+0000", "method": "Polish Banks", "sum": { "amount": 1000, "currency": "PLN" }, "description": "" }, "customer": { "id": "customer2" }, "operation": { "id": 92939010024021, "type": "sale", "status": "decline", "date": "2020-11-03T15:47:39+0000", "created_date": "2020-11-03T15:47:02+0000", "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940", "sum_initial": { "amount": 1000, "currency": "PLN" }, "sum_converted": { "amount": 1000, "currency": "PLN" }, "code": "20000", "message": "General decline", "provider": { "id": 3901, "payment_id": "" } }, "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg==" }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
Оплаты через Gate
Общая информация
Для оплаты через Gate с использованием метода Open Banking in Poland со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Осуществить перенаправление к сервису провайдера.
- Принять оповещение от платежной платформы ecommpay о результате оплаты.
Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Gate. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату через один из банков, поддерживающих работу с методом Open Banking in Poland.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
- На стороне платёжной платформы выполняется дальнейшая обработка запроса.
- От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера.
- Пользователь перенаправляется к сервису провайдера, а затем — к сервису банка, где пользователю отображается платёжная инструкция.
- Пользователь выполняет необходимые действия для проведения оплаты.
- На стороне сервиса банка выполняется обработка платежа.
- Информация о результате оплаты отображается пользователю на стороне сервиса банка.
- Пользователь перенаправляется к веб-сервису мерчанта.
- От сервиса банка к сервису провайдера направляется уведомление о результате оплаты.
- От сервиса провайдера к платёжной платформе направляется уведомление о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От веб-сервиса пользователю направляется информация о результате оплаты.
Информация о формате запросов и параметрах инициации оплат методом Open Banking in Poland через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API представлена в разделе Работа с API.
Формат запросов
При работе с запросами на оплаты с применением метода Open Banking in Poland необходимо учитывать следующее:
- Должен использоваться запрос к конечной точке
/v2/payment/banks/poland/sale
, отправляемый методом POST. Этот запрос относится к группе запросов /v2/payment/banks/{payment_method}/sale. - В запросе должны использоваться следующие объекты и параметры:
- 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 для перенаправления пользователя в веб-сервис:
- success — URL для перенаправления в случае проведённого платежа;
- decline — URL для перенаправления в случае отклонённого платежа;
- return — URL для перенаправления пользователя на любом шаге оплаты.
- general — объект, содержащий основные идентификационные сведения запроса:
- Дополнительно могут использоваться любые другие параметры, указанные в спецификации.
Таким образом, корректный запрос на оплату с применением метода Open Banking in Poland должен содержать идентификаторы проекта, пользователя и платежа, подпись, сумму и валюту платежа, информацию о пользователе, идентификатор банка и URL для перенаправления:
Рис.: Пример запроса на оплату
{ "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 1000, "currency": "PLN" }, "customer": { "id": "customer1", "ip_address": "1.1.1.1" }, "account":{ "bank_id": 22411 }, "return_url":{ "success": "http://example.com/success", "decline": "http://example.com/decline", "return": "http://example.com/return" } }
Форматы данных для перенаправления пользователей
Для перенаправления пользователя от веб-сервиса к сервису провайдера необходимо:
- Принять от платёжной платформы оповещение с объектом redirect_data, содержащим в объекте body данные для подключения JavaScript-библиотеки провайдера и вызова функции перенаправления к сервису провайдера.
- Подключить JavaScript-библиотеку провайдера, ссылка на которую указана в параметре widget_url объекта body.
- Вызвать функцию перенаправления к сервису провайдера с использованием параметров, переданных в объекте 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": { "method": "POST", "url": "http://pay.test/example", "body": { "widget_url":"https://psd2.neopay.lt/widget.js", "widget_host":"https://psd2.neopay.lt/", "token": "eyJhbGciOiJIUzI1NiIsInR5cCIp0cnVlLCJpYXQiOjE0OTMyMD", "other": "off", "creditor": "XXXYYY12", "css": "https://css.test.org", "default_country": "PL", "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': 'XXXYYY12', 'css':'https://css.test.org', 'default_country':'PL', 'callback_url':'https://callback.url.org' } );
Формат оповещений
Для оповещений о результатах оплат с применением метода Open Banking in Poland используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 239
была успешно проведена оплата в размере 10,00 PLN
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 239, "payment": { "id": "ABC12345", "type": "purchase", "status": "success", "date": "2020-11-03T14:41:38+0000", "method": "Polish Banks", "sum": { "amount": 1000, "currency": "PLN" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 77796010023511, "type": "sale", "status": "success", "date": "2020-11-03T14:41:38+0000", "created_date": "2020-11-03T14:39:34+0000", "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797", "sum_initial": { "amount": 1000, "currency": "PLN" }, "sum_converted": { "amount": 1000, "currency": "PLN" }, "code": "0", "message": "Success", "provider": { "id": 3901, "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf", "auth_code": "" } }, "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw==" }
В следующем примере оплата была отклонена.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 10801, "payment": { "id": "ABC67890", "type": "purchase", "status": "decline", "date": "2020-11-03T15:47:39+0000", "method": "Polish Banks", "sum": { "amount": 1000, "currency": "PLN" }, "description": "" }, "customer": { "id": "customer2" }, "operation": { "id": 92939010024021, "type": "sale", "status": "decline", "date": "2020-11-03T15:47:39+0000", "created_date": "2020-11-03T15:47:02+0000", "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940", "sum_initial": { "amount": 1000, "currency": "PLN" }, "sum_converted": { "amount": 1000, "currency": "PLN" }, "code": "20000", "message": "General decline", "provider": { "id": 3901, "payment_id": "" } }, "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg==" }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
Анализ результатов проведения платежей
Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода Open Banking in Poland доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.
Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей на вкладке Analytics.
Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:
- Dashboard позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
- Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.
С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ecommpay.