Open Banking in Finland

Обзор

Введение

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

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

В этой статье представлена информация о работе с методом Open Banking in Finland: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.

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

Тип платёжного метода банковские платежи
Платёжные инструменты банковские счета
Регионы использования FI
Валюты платежей EUR
Конвертация валют на стороне ecommpay
Разовые оплаты +
Повторяемые оплаты
Полные возвраты
Частичные возвраты
Выплаты
Опротестования
Особенности
  • при работе с методом Open Banking in Finland пользователи должны предоставлять дополнительное согласие на проведение платежей с использованием открытых банковских протоколов, что добавляет в платёжные сценарии соответствующие шаги (подробнее далее)
  • при работе с Payment Page можно использовать разные варианты выбора метода и банка (подробнее далее)
  • при перенаправлении к сервису провайдера не может использоваться вариант с применением элемента iframe; страница этого сервиса может открываться в отдельной вкладке или в модальном окне
  • перенаправление к сервису провайдера не может осуществляться через элемент iframe
  • при проведении оплат может использоваться процедура получения подтверждения о зачислении средств (подробнее далее)
  • для проведения выплат можно использовать комплементарный метод Выплаты на банковские счета в ЕЗПЕ (SEPA)
Организация и стоимость подключения по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить на портале ecommpay shop

Схема работы

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

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



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

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

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

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

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

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

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

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

Табл. 1. Список банков
Банк ID
Aktia Bank 4971
Alandsbanken 55361
Danske Bank 55321
Handelsbanken 4981
Nordea Bank 4991
OmaSp 55331
OP Bank 5001
POP Pankki 55341
Saastopankki 55351
S-Pankki 55371

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

Рис. 1. Пример данных из запроса на получение списка банков
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
Рис. 2. Пример данных из ответа с информацией о банках
[
  {
    "id": 4981, // Индентификатор банка
    "abbr": "HANDELSBANKEN", // Служебная аббревиатура банка (для внутреннего применения)
    "name": "Handelsbanken", // Основное название банка
    "nativeName": "Handelsbanken", // Локальное название банка
    "currencies": [ // Массив с информацией о валютах, поддерживаемых банком
      {
        "id": 978, // Идентификатор валюты в платёжной платформе
        "alpha_3_4217": "EUR", // Буквенный код валюты платежа в формате ISO-4217 alpha-3
        "number_3_4217": "978", // Цифоровой код валюты платежа в формате ISO-4217 alpha-3
        "exponent": 2 // Число дробных разрядов валюты
      }
    ]
  },
  {
    "id": 4991,
    "abbr": "NORDEA-FINLAND",
    "name": "Nordea Bank",
    "nativeName": "Nordea Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 55371,
    "abbr": "S-PANKKI",
    "name": "S-Pankki",
    "nativeName": "S-Pankki",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]

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

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

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

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

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

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

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

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



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

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

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

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

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

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

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

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

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

    1. Через выбор в Payment Page метода и банка (1) — как вариант по умолчанию, применяемый, если не указываются параметры force_payment_method и payment_methods_options, упоминаемые в подпунктах 2–6.
    2. Через выбор в Payment Page банка среди доступных методов (2) — для этого необходимо указывать в значении параметра payment_methods_options строковый объект, названием которого выступает указатель метода (online_finnish_banks), а содержимым — параметр split_banks со значением true. При этом в записи такого объекта все вложенные символы " (U+0022) должны экранироваться с помощью предшествующих им символов \ (U+005C).
      "payment_methods_options": "{\"online_finnish_banks\": {\"split_banks\": true}}"

      В результате использования такого варианта для метода Open Banking in Finland вместо кнопки его выбора отображаются кнопки выбора всех банков, поддерживающих работу с ним.

    3. Через выбор в Payment Page банка среди методов заданной группы (3) — для этого необходимо:
      • Указывать в значении параметра payment_methods_options строковый объект, названием которого выступает указатель метода (online_finnish_banks), а содержимым — параметр split_banks со значением true. При этом в записи такого объекта все вложенные символы " (U+0022) должны экранироваться с помощью предшествующих им символов \ (U+005C).
      • Указывать в значении параметра force_payment_group код группы openbanking.
      "payment_methods_options": "{\"online_finnish_banks\": {\"split_banks\": true}}",
      "force_payment_group": "openbanking"

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

    4. Через выбор в Payment Page банка из числа доступных (4) — для этого необходимо указывать в значении параметра force_payment_method код предварительного выбора метода online-finnish-banks.
      "force_payment_method": "online-finnish-banks"

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

    5. Через выбор в Payment Page банка из числа заданных (5) — для этого необходимо:
      • Указывать в значении параметра payment_methods_options строковый объект, названием которого выступает указатель метода (online_finnish_banks), а содержимым — параметр split_banks со значением true и массив banks_id с идентификаторами целевых банков. При этом в записи такого объекта все вложенные символы " (U+0022) должны экранироваться с помощью предшествующих им символов \ (U+005C).
      • Указывать в значении параметра force_payment_method код предварительного выбора метода online-finnish-banks.
      "payment_methods_options": "{\"online_finnish_banks\": {\"split_banks\": true, \"banks_id\": [4981, 4991]}}",
      "force_payment_method": "online-finnish-banks"

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

    6. Через подтверждение в Payment Page перенаправления к сервису заданного банка (6) — для этого необходимо:
      • Указывать в значении параметра payment_methods_options строковый объект, названием которого выступает указатель метода (online_finnish_banks), а содержимым — параметр split_banks со значением true и массив banks_id с идентификатором целевого банка. При этом в записи такого объекта все вложенные символы " (U+0022) должны экранироваться с помощью предшествующих им символов \ (U+005C).
      • Указывать в значении параметра force_payment_method код предварительного выбора метода online-finnish-banks.
      "payment_methods_options": "{\"online_finnish_banks\": {\"split_banks\": true, \"banks_id\": [4981]}}",
      "force_payment_method": "online-finnish-banks"

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

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

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

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

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "force_payment_method": "online-finnish-banks",
   "payment_methods_options": {"test-code": {"split_banks": true, "banks_id": [4991, 4981]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

Рис. 11. Пример данных из оповещения о проведении оплаты
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Finnish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "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": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }

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

Рис. 12. Пример данных из оповещения об отклонении оплаты
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Finnish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "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": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }

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

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

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

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

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

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

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

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

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



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

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

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

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

  1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/finland/sale, которая относится к группе /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 для возвращения пользователя к веб-сервису:
      • success — URL для перенаправления в случае проведённого платежа;
      • decline — URL для перенаправления в случае отклонённого платежа;
      • return — URL для возвращения пользователя к веб-сервису при работе с сервисом провайдера или банка в тех случаях, когда пользователь отказывается от проведения платежа.
  3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}
Рис. 14. Пример достаточного набора данных для запроса на оплату
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}

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

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

  • body — объект с данными для отправки в теле запроса;
  • method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
  • url — параметр со ссылкой для перенаправления.
Рис. 15. Пример объекта redirect_data
"redirect_data": {
        "method": "POST",
        "body": [],
        "encrypted": [],
        "url": "https://web-app.example.com/app/request-token/rq:3R123"
    }

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

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

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

Рис. 16. Пример данных из оповещения о проведении оплаты
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Finnish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "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": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }

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

Рис. 17. Пример данных из оповещения об отклонении оплаты
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Finnish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "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": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }

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

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

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

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

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

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