Open Banking (группа методов)

Обзор

Введение

Open Banking — группа методов интернет-банкинга, базирующихся на применении открытых банковских протоколов и обеспечивающих расширенные возможности для защищённой работы с информацией о пользователях. Методы этой группы характеризуются совокупностью схожих свойств и позволяют проводить платежи в евро и ряде других европейских валют через различные банки Европы с использованием банковских счетов. Вместе с тем, каждый из методов локализуется на отдельной стране, с учётом её специфики.

В платёжной платформе ecommpay поддерживаются оплаты методами Open Banking. Для проведения выплат, в том числе в целях возврата средств по проведённым оплатам, при работе с этими методами могут использоваться комплементарные методы «Выплаты на банковские счета в ЕЗПЕ (SEPA)» и «Локальные выплаты на банковские счета в Великобритании».

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

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

В этой статье представлена общая информация о работе с методами группы Open Banking. Специализированная информация о каждом из методов Open Banking представлена в статьях с описаниями этих методов.

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

Обобщённые свойства методов группы Open Banking можно представить следующим образом.


Тип платёжного метода	банковские платежи
Платёжные инструменты	банковские счета
Регионы использования	AT, BE, EE, ES, FI, FR, DE, GR, HU, LT, LV, NL, NO, PL, PT, RO, SE
Валюты платежей	EUR (для AT, BE, EE, ES, FI, FR, DE, GR, LT, LV, NL, PL, PT, RO), HUF (для HU), NOK (для NO), PLN (for PL), RON (для RO), SEK (для SE)
Конвертация валют	на стороне ecommpay
Разовые оплаты	+
Повторяемые оплаты	–
Полные возвраты	–
Частичные возвраты	–
Выплаты	–
Опротестования	–
Особенности	с учётом специфики задействуемых провайдеров и банков в некоторых случаях пользователи должны предоставлять дополнительное согласие на проведение платежей с использованием открытых банковских протоколов, что добавляет в платёжные сценарии соответствующие шаги (подробнее далее) при работе с Payment Page можно использовать разные варианты выбора метода и банка (подробнее далее) при перенаправлениях к сервисам провайдеров и банков не может использоваться вариант с применением элемента iframe; страницы этих сервисов могут открываться в отдельной вкладке или в модальном окне при проведении оплат может использоваться процедура получения подтверждения о зачислении средств (подробнее далее) для проведения выплат можно использовать комплементарные методы «Выплаты на банковские счета в ЕЗПЕ (SEPA)» и «Локальные выплаты на банковские счета в Великобритании»
Организация и стоимость подключения	по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить на портале ecommpay shop

Схема работы

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

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

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

Для проведения оплат с использованием методов группы Open Banking могут применяться различные интерфейсы платёжной платформы: Payment Page, Gate и Dashboard (с применением платёжных ссылок на открытие Payment Page). При этом, независимо от интерфейса, для каждой оплаты применимы ограничения по сумме и времени — с учётом того, через какого провайдера и какой банк эта оплата проводится.

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

Оплаты с использованием методов группы Open Banking проводятся с перенаправлением пользователей к сервисам провайдера (если необходимо) и банка.

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

Общие сценарии проведения оплат через Payment Page и Gate можно представить следующим образом.

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

Вместе с тем, к особенностям работы с методами группы Open Banking можно отнести то, что для каждого платежа с использованием любого из этих методов должен быть выбран конкретный банк. При работе через Payment Page, как правило, выбор банка осуществляется пользователем уже в платёжной форме, но при вызовах Payment Page с предварительным выбором метода и банка, а также при инициировании оплат через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Возможные варианты выбора банка при работе через Payment Page описаны в разделе Оплаты через Payment Page этой статьи, а способы работы с идентификаторами банков — в следующем подразделе, Поддержка со стороны банков.

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

В проведении платежей с использованием какого-либо из методов группы Open Banking могут задействоваться различные банки, поддерживающие этот метод. Поскольку со временем состав таких банков может меняться, для получения актуальной информации о них рекомендуется использовать POST-запросы к конечным точкам группы /v2/info/banks/{payment_method}/{operationType}/list Gate API. Для методов Open Banking названием каталога {payment_method} выступает название страны (в соответствии с тем, как оно указано в описании метода), а названием каталога {operationType} — тип операции (sale). Так, для метода Open Banking in Germany применим запрос к конечной точке /v2/info/banks/germany/sale/list.

В проведении платежей с использованием методов Open Banking могут задействоваться различные банки. Для получения актуальной информации о доступных для конкретного метода банках рекомендуется использовать POST-запросы к конечным точкам группы /v2/info/banks/{payment_method}/{operationType}/list Gate API. При этом в качестве названия каталога {payment_method} следует использовать название страны (в соответствии с тем, как оно указано в описании метода), а в качестве названия каталога {operationType} — тип операции (sale). Так, для метода Open Banking in Germany применим запрос к конечной точке /v2/info/banks/germany/sale/list.

В каждом запросе на информацию о доступных банках для проведения оплат одним из методов группы Open Banking должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений.

Рис. 11. Пример данных из запроса на получение списка банков

{
    "general": {
        "project_id": 200,
        "payment_id": "ORDER_155860015",
        "signature": "K6jllym+PtObocZtr345st...=="
    },
    "payment": {
        "amount": 1000,
        "currency": "EUR"
    }
}

Рис. 12. Пример данных из ответа с информацией о банках

[
  {
    "id": 54991, // Индентификатор банка
    "abbr": "COMMERZBANK", // Служебное название банка в платформе (или его аббревиатура)
    "name": "Commerzbank", // Основное (международное) название банка
    "nativeName": "Commerzbank", // Локальное (национальное или региональное) название банка
    "currencies": [ // Массив с информацией о валютах, поддерживаемых банком
      {
        "id": 978, // Идентификатор валюты в платёжной платформе
        "alpha_3_4217": "EUR", // Буквенный код валюты в формате ISO-4217 alpha-3
        "number_3_4217": "978", // Цифровой код валюты в формате ISO-4217 alpha-3
        "exponent": 2 // Число дробных разрядов валюты
      }
    ]
  },
  {
    "id": 54981,
    "abbr": "UNICREDIT-BANK",
    "name": "UniCredit Bank",
    "nativeName": "UniCredit Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 54971,
    "abbr": "DEUTSCHE-BANK",
    "name": "Deutsche Bank",
    "nativeName": "Deutsche Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]

С вопросами о работе с банками, поддерживающими методы группы Open Banking, можно обращаться к курирующему менеджеру ecommpay.

Подтверждение зачисления средств

В некоторых случаях при проведении оплат с использованием методов группы Open Banking обработка платежей на стороне провайдеров и банков может занимать продолжительное время: вплоть до семи дней и даже больше. В связи с этим возможны ситуации, когда первичная информация о проведении или отклонении платежа не соответствует итоговому результату (например, при получении в платформе информации от провайдера об отклонении платежа позднее средства могут быть всё же зачислены на счёт получателя, и наоборот).

Чтобы обеспечивать в таких случаях корректное уведомление мерчантов о состоянии платежей, в платёжной платформе ecommpay применяется процедура подтверждения зачисления средств получателю. При подключении методов группы Open Banking рекомендуется согласовывать с курирующим менеджером применение этой процедуры, а также перевод платежей, по которым получено подтверждение о том, что средства не зачислены, в статус reversed или decline (это может быть удобным для контроля и анализа платежей).

Подтверждение зачисления средств выполняется следующим образом:

После выполнения пользователем всех необходимых действий платёж поступает в обработку на стороне сервиса провайдера или банка, в то время как пользователь возвращается к платёжному интерфейсу (Payment Page или веб-сервиса), где получает информацию о приёме платежа в обработку.
На стороне платёжной платформы выполняется ряд действий:
1. Формируется операция payment confirmation.
2. Платежу присваивается статус awaiting confirmation — до получения со стороны провайдера информации о зачислении средств.
3. К веб-сервису отправляется оповещение об изменении статуса платежа.
4. Операции sale присваивается статус success или decline (в зависимости от специфики провайдера или банка) — до получения со стороны провайдера информации о зачислении средств.
5. К веб-сервису отправляется оповещение об изменении статуса операции.
На стороне провайдера определяется итоговый статус зачисления средств, после чего информация об этом статусе отправляется к платёжной платформе.
На стороне платёжной платформы обеспечивается обработка полученной информации, в результате чего операции payment confirmation и платежу присваиваются итоговые статусы и к веб-сервису отправляются соответствующие оповещения.

Для операции payment confirmation предусмотрены следующие итоговые статусы:

success — при получении со стороны провайдера подтверждения того, что средства зачислены. В этом случае платежу присваивается статус success и к веб-сервису отправляется итоговое оповещение с информацией о результате оплаты.
decline — при получении со стороны провайдера информации о том, что средства не зачислены, либо при отсутствии со стороны провайдера информации о зачислении средств по истечении установленного срока (который по умолчанию составляет 7 дней и может быть изменён через обращение к специалистам технической поддержки ecommpay).
В таких случаях, с учётом свойств проекта на стороне платёжной платформы, выполняется один из двух сценариев:
- Формируется операция reversal и к веб-сервису последовательно отправляются соответствующие оповещения: промежуточное, с информацией о том, что средства не были зачислены, и итоговое, с информацией о возврате средств и переводе платежа в статус reversed.
- Платёж переводится в статус decline и к веб-сервису направляется итоговое оповещение с информацией об отклонении оплаты.

Если помимо получения информации, передаваемой в оповещениях, требуется дополнительно отслеживать изменение статусов платежей и операций, это можно делать с использованием Gate API (через ответы на запросы о состоянии платежа), а также через интерфейс Dashboard.

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

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

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

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

Внимание: При перенаправлениях к сервисам провайдеров и банков не может использоваться вариант с применением элемента iframe. Страницы этих сервисов могут открываться в отдельной вкладке или в модальном окне (независимо от способа открытия Payment Page).

Общая схема проведения оплаты выглядит следующим образом.

Рис. 13. Проведение оплаты через Payment Page. Описание шагов

Пользователь на стороне веб-сервиса инициирует оплату.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
Запрос на проведение оплаты поступает в платёжную платформу.
В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
Осуществляется подготовка к открытию платёжной формы согласно параметрам проекта и вызова.
Пользователю отображается платёжная форма.
Пользователь выбирает один из платёжных методов Open Banking и один из банков, поддерживающих работу с этим методом.
В платёжную платформу передаётся запрос на проведение оплаты с использованием выбранного метода.
В платёжной платформе выполняется обработка полученного запроса, с выявлением необходимости в получении дополнительного согласия пользователя и дополнительных сведений о нём. Если необходимо получить такое согласие (и сведения), выполняются следующие шаги:
1. От платёжной платформы к Payment Page направляется информация о необходимости получения дополнительного согласия пользователя на проведение оплаты и, если актуально, дополнительных сведений.
2. В Payment Page пользователю отображаются уведомление о необходимости подтвердить проведение оплаты и, если актуально, поля, которые необходимо заполнить для продолжения платежа.
3. Пользователь предоставляет необходимые сведения (если они были запрошены), соглашается с указанной информацией и подтверждает проведение платежа.
4. От Payment Page к платёжной платформе отправляется запрос на продолжение платежа с предоставленными пользователем сведениями.
5. На стороне платёжной платформы выполняется обработка полученной информации.
От платёжной платформы к Payment Page передаются данные для перенаправления пользователя к сервису провайдера или банка.
Пользователь перенаправляется к требуемому сервису — провайдера или банка, — где ему отображается платёжная инструкция.
Пользователь выполняет необходимые действия для оплаты на стороне используемого сервиса.
На стороне используемого сервиса выполняется обработка оплаты.
Информация о результате оплаты отображается пользователю на стороне используемого сервиса.
Пользователь перенаправляется к Payment Page.
От используемого сервиса к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
От платёжной платформы к Payment Page направляется информация о результате оплаты.
Информация о результате оплаты отображается пользователю в Payment Page.

Как правило, после того как пользователь на стороне веб-сервиса подтверждает готовность перейти к оплате, он перенаправляется к Payment Page, выбирает платёжный метод и, в случае работы с методами группы Open Banking, дополнительно выбирает один из доступных банков. Вместе с тем, в некоторых ситуациях могут быть актуальны другие варианты выбора платёжного метода и банка. Например, при открытии Payment Page можно сразу перенаправлять пользователя к выбору банка либо ограничивать список поддерживаемых банков для отдельного платежа и отображать пользователю только кнопки выбора целевых банков. И со стороны веб-сервиса можно управлять применением таких вариантов.

Конкретный вариант выбора платёжного метода и банка определяется через параметры, указанные в запросе на открытие Payment Page (подробнее), при этом допустимы следующие варианты:

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

При работе с такими оплатами можно использовать следующие варианты выбора метода и банка.

Рис. 15. 2 — Выбор банка среди доступных методов

Рис. 16. 3 — Выбор банка среди методов заданной группы

Рис. 17. 4 — Выбор среди доступных банков

Рис. 18. 5 — Выбор среди заданных банков

Рис. 19. 6 — Перенаправление к сервису заданного банка

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

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

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

Должен использоваться базовый минимум параметров, обязательный для любого платежа:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа в дробных единицах валюты;
- customer_id — идентификатор пользователя в рамках проекта.
Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
Для проведения платежа могут требоваться дополнительные параметры, состав которых зависит от метода, страны, провайдера и банка. Если такие параметры отсутствуют в запросе, в платёжной форме пользователю могут отображаться поля для их указания (подробнее). Подробнее об уточнении параметров — в статье Дополнение информации о платежах.
Также в некоторых случаях, с учётом специфики используемых провайдеров и банков, пользователю может требоваться указывать в Payment Page номер счёта (International Bank Account Number, IBAN), в то время как в других случаях этот номер указывается пользователем уже на стороне провайдера или банка. Поскольку этот номер может указываться только пользователем, он не может быть учтён на стороне провайдера или банка даже при его указании в исходном запросе и должен указываться отдельно.
Поскольку при проведении платежа может требоваться дополнительное согласие пользователя, рекомендуется передавать параметр merchant_return_url с указанием адреса для предварительного возвращения пользователя к веб-сервису — чтобы в случае отказа от предоставления согласия пользователь мог вернуться к веб-сервису с помощью соответствующей ссылки в платёжной форме.
Вариант выбора банка может определяться следующим образом (с примерами значений для метода Open Banking in Germany):
1. Через выбор в Payment Page метода и банка (1) — как вариант по умолчанию, применяемый, если не указываются параметры force_payment_method и payment_methods_options, упоминаемые в подпунктах 2–6.
2. Через выбор в Payment Page банка среди доступных методов (2) — для этого необходимо указывать в значении параметра payment_methods_options строковый объект, названием которого выступает указатель метода (online_german_banks), а содержимым — параметр split_banks со значением true. При этом в записи такого объекта все вложенные символы " (U+0022) должны экранироваться с помощью предшествующих им символов \ (U+005C).
```
"payment_methods_options": "{\"online_german_banks\": {\"split_banks\": true}}"
```
  В результате использования такого варианта для указанного метода вместо кнопки его выбора отображаются кнопки выбора всех банков, поддерживающих работу с ним.
3. Через выбор в Payment Page банка среди методов заданной группы (3) — для этого необходимо:
  - Указывать в значении параметра payment_methods_options строковый объект, названием которого выступает указатель метода (online_german_banks), а содержимым — параметр split_banks со значением true. При этом в записи такого объекта все вложенные символы " (U+0022) должны экранироваться с помощью предшествующих им символов \ (U+005C).
  - Указывать в значении параметра force_payment_group код группы openbanking.
```
"payment_methods_options": "{\"online_german_banks\": {\"split_banks\": true}}",
"force_payment_group": "openbanking"
```
  В результате использования такого варианта в платёжной форме отображаются кнопки выбора всех банков, поддерживающих работу с указанным методом, и кнопки выбора других методов группы Open Banking.
4. Через выбор в Payment Page банка из числа доступных (4) — для этого необходимо указывать в значении параметра force_payment_method код предварительного выбора целевого метода группы Open Banking (online-german-banks).
```
"force_payment_method": "online-german-banks"
```
  В результате использования такого варианта в платёжной форме отображаются кнопки выбора всех банков, поддерживающих работу с указанным методом.
5. Через выбор в Payment Page банка из числа заданных (5) — для этого необходимо:
  - Указывать в значении параметра payment_methods_options строковый объект, названием которого выступает указатель метода (online_german_banks), а содержимым — параметр split_banks со значением true и массив banks_id с идентификаторами целевых банков. При этом в записи такого объекта все вложенные символы " (U+0022) должны экранироваться с помощью предшествующих им символов \ (U+005C).
  - Указывать в значении параметра force_payment_method код предварительного выбора целевого метода группы Open Banking (online-german-banks).
```
"payment_methods_options": "{\"online_german_banks\": {\"split_banks\": true, \"banks_id\": [54971, 54981]}}",
"force_payment_method": "online-german-banks"
```
  В результате использования такого варианта в платёжной форме отображаются кнопки выбора заданных банков, поддерживающих работу с указанным методом.
6. Через подтверждение в Payment Page перенаправления к сервису заданного банка (6) — для этого необходимо:
  - Указывать в значении параметра payment_methods_options строковый объект, названием которого выступает указатель метода (online_german_banks), а содержимым — параметр split_banks со значением true и массив banks_id с идентификатором целевого банка. При этом в записи такого объекта все вложенные символы " (U+0022) должны экранироваться с помощью предшествующих им символов \ (U+005C).
  - Указывать в значении параметра force_payment_method код предварительного выбора целевого метода группы Open Banking (online-german-banks).
```
"payment_methods_options": "{\"online_german_banks\": {\"split_banks\": true, \"banks_id\": [54971]}}",
"force_payment_method": "online-german-banks"
```
  В результате использования такого варианта при открытии платёжной формы в ней отображается страница подтверждения для перенаправления к сервису заданного банка.
Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
После указания всех целевых параметров необходимо составлять подпись (подробнее).

Таким образом, корректный запрос на открытие платёжной формы с применением одного из методов группы Open Banking должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор пользователя и подпись, а также может содержать различные дополнительные параметры.

{ 
 // обязательные параметры  
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
 // дополнительные параметры
    ...
 // подпись
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Рис. 20. Пример набора данных для запроса на оплату

{ 
 // обязательные параметры  
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
 // дополнительные параметры
    ...
 // подпись
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

В случае с выбором из заданных банков (вариант 5) для метода Open Banking in Germany запрос на открытие Payment Page может содержать следующий набор данных.

{
 // обязательные параметры  
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
 // дополнительные параметры
   ...
   "force_payment_method": "online-german-banks",
   "payment_methods_options": "{\"online_german_banks\": {\"split_banks\": true, \"banks_id\": [54971, 54981]}}"
 // подпись
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

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

{
        "project_id": 200,
        "payment": {
            "id": "order_487",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "German Banks", // Указание на использованный метод
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Book order"
        },
        "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=="
    }

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

Рис. 22. Пример данных из оповещения об отклонении оплаты

{
        "project_id": 200,
        "payment": {
            "id": "order_488",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "German Banks", // Указание на использованный метод
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Book order"
        },
        "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 также могут быть полезны следующие материалы:

Быстрый старт и Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
Разовая оплата в одну стадию — о том, как проводить разовые оплаты с незамедлительным списанием средств через Payment Page.
Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.

Оплаты через Gate

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

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

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

Информация о форматах данных, используемых для получения согласия пользователя и его перенаправления, представлена далее в этом разделе.

Общая схема проведения оплаты выглядит следующим образом.

Рис. 23. Проведение оплаты через Gate. Описание шагов

Пользователь на стороне веб-сервиса инициирует оплату одним из методов группы Open Banking с выбором одного из банков.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
Запрос на проведение оплаты поступает в платёжную платформу.
В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
В платёжной платформе выполняются дальнейшая обработка полученного запроса (с проверкой корректности и согласованности параметров). При этом на стороне провайдера выявляется необходимость в получении дополнительного согласия пользователя и дополнительных сведений о нём. Если необходимо получить такое согласие (и сведения), выполняются следующие шаги:
1. От платёжной платформы к веб-сервису направляется оповещение о необходимости получения дополнительного согласия пользователя на проведение оплаты и, если актуально, дополнительных сведений.
2. На стороне веб-сервиса запрашиваются согласие пользователя на проведение платежа и, если требуется, дополнительные сведения.
3. Пользователь предоставляет запрашиваемые сведения, соглашается с указанной информацией и подтверждает проведение платежа.
4. От веб-сервиса к платёжной платформе отправляется запрос на продолжение платежа с предоставленными пользователем сведениями.
5. На стороне платёжной платформы выполняется обработка полученной информации.
От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера или банка.
Пользователь перенаправляется к требуемому сервису — провайдера или банка, — где ему отображается платёжная инструкция.
Пользователь выполняет необходимые действия для оплаты на стороне используемого сервиса.
На стороне используемого сервиса выполняется обработка оплаты.
Информация о результате оплаты отображается пользователю на стороне используемого сервиса.
Пользователь перенаправляется к веб-сервису мерчанта.
От используемого сервиса к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

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

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

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

Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/{payment_method}/sale, где названием каталога {payment_method} выступает название страны (в соответствии с тем, как оно указано в описании метода; так, для Германии используется germany).
В каждом запросе должны использоваться следующие объекты и параметры:
- 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 для возвращения пользователя к веб-сервису при работе с сервисом провайдера или банка в тех случаях, когда пользователь отказывается от проведения платежа.
Для проведения платежа могут требоваться дополнительные параметры, состав которых зависит от метода, страны, провайдера и банка. Если такие параметры отсутствуют в исходном запросе, их список отправляется в оповещении о необходимости дополнить данные. Для улучшения пользовательского опыта рекомендуется передавать такие параметры в исходных запросах.
Кроме того, в некоторых случаях, в силу специфики методов группы, даже если в исходном запросе был указан номер счёта (International Bank Account Number, IBAN), он всё равно запрашивается дополнительно, через указание объекта account с параметром number в оповещении на уточнение.
Кроме того, в некоторых случаях, с учётом специфики используемого провайдера или банка, пользователю может требоваться указывать на стороне веб-сервиса номер счёта (International Bank Account Number, IBAN), в то время как в других случаях этот номер указывается пользователем на стороне провайдера или банка. При этом, в силу специфики методов группы, даже если номер счёта пользователя указывается в исходном запросе, он не учитывается при первичной обработке этого запроса и может быть запрошен отдельно, через указание объекта account с параметром number в оповещении на уточнение (вместе с указанием других актуальных параметров, если они не были переданы).
Подробнее об уточнении параметров — в статье Дополнение информации о платеже.
Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением методов группы Open Banking должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, идентификатор банка, URL для перенаправления и подпись, а также может содержать дополнительные параметры.

{
 // обязательные параметры  
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7IipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer123",  
      "ip_address": "192.0.2.0"
    },
    "account": {
      "bank_id": 54981
    },
    "return_url":{
      "return": "http://example.com/return"
 // дополнительные параметры
    ...
 }
}

Рис. 24. Пример набора данных для запроса на оплату

{
 // обязательные параметры  
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7IipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer123",  
      "ip_address": "192.0.2.0"
    },
    "account": {
      "bank_id": 54981
    },
    "return_url":{
      "return": "http://example.com/return"
 // дополнительные параметры
    ...
 }
}

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

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

параметр customer.properties.psu_consent_text.default с текстом, который необходимо отобразить пользователю для получения его согласия на проведение платежа;
параметры, по которым необходимо предоставить дополнительные сведения о пользователе (если это актуально).

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

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

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

После получения на стороне веб-сервиса согласия пользователя и запрошенных сведений каждый раз необходимо отправлять POST-запрос на продолжение платежа —. Такой запрос должен отправляться к конечной точке /v2/payment/clarification методом POST, и в него должны включаться следующие объекты и параметры, с использованием следующих объектов и параметров:

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

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

{
    "general": {
        "project_id": 10571,
        "payment_id": "1234567890",
        "signature": "PJkV8ej\/UG0Di8jQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "additional_data": {
        "customer": {
            "psu_consent": "1",
            "psu_consent_text": "The consent text displayed to the customer"
        }
    }
 ...
}

Рис. 25. Пример набора данных для запроса на продолжение платежа

{
    "general": {
        "project_id": 10571,
        "payment_id": "1234567890",
        "signature": "PJkV8ej\/UG0Di8jQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "additional_data": {
        "customer": {
            "psu_consent": "1",
            "psu_consent_text": "The consent text displayed to the customer"
        }
    }
 ...
}

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

Для перенаправления пользователей от веб-сервиса мерчанта к сервису провайдера или банка при проведении каждого платежа с использованием методов группы Open Banking необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data включаются следующие объекты и параметры:

body — объект с данными для отправки в теле запроса (с учётом специфики конкретного метода этот объект может содержать различную информацию);
method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
url — параметр со ссылкой для перенаправления.

Рис. 26. Пример объекта redirect_data

  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }

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

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

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

{
        "project_id": 200,
        "payment": {
            "id": "order_487",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "German Banks", // Указание на использованный метод
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Book order"
        },
        "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=="
    }

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

Рис. 28. Пример данных из оповещения об отклонении оплаты

{
        "project_id": 200,
        "payment": {
            "id": "order_488",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "German Banks", // Указание на использованный метод
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Book order"
        },
        "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 также могут быть полезны следующие материалы:

Быстрый старт и Организация взаимодействия — о том, как организовать взаимодействие с платёжной платформой через Gate.
Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
Разовая оплата в одну стадию — о том, как проводить разовые оплаты с незамедлительным списанием средств через Gate.
Работа с информацией об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.

Анализ результатов проведения платежей

Для анализа информации о платежах и операциях, как по отдельным методам Open Banking, так и по всем актуальным платёжным методам, можно использовать:

инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
данные в формате JSON, получаемые по программным запросам через интерфейс Data API.

С вопросами по анализу информации о платежах и операциях можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.