Open Banking in Spain

Обзор

Введение

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

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

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

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

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

Схема работы

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

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



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

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

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

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

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

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

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

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

Табл. 1. Список банков
Банк ID
Banco Sabadell 56611
Bankinter 56621
Bantierra 56631
BBVA 56641
Caixa Bank 56651
Caixa Popular 56661
Caixa Rural Benicarlo 56671
Caja Rural de Asturias 56681
Caja Rural de Baena 56691
Caja Rural de Casas Ibanez 56701
Caja Rural de Extremadura 56711
Caja Rural de Jaen 56721
Caja Rural de Navarra 56731
Caja Rural de Onda 56741
Caja Rural de Rural Nostra 56751
Caja Rural de Salamanca 56761
Caja Rural de San Jose de Almassora 56771
Caja Rural de Soria 56781
Caja Rural de Villamalea 56791
Caja Rural de Zamora 56801
Caja Siete 56811
ING 56821
Kutxabank 56831
Santander 56841
Targobank 56851
Unicaja Banco 56861

Поскольку со временем состав доступных банков может меняться, дляДля получения актуальной информации о доступных банках рекомендуется использовать POST-запросы к конечной точке /v2/info/banks/spain/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": 56611, // Индентификатор банка
    "abbr": "T-SABADELES", // Служебное название банка в платформе (или его аббревиатура)
    "name": "Banco Sabadell", // Основное (международное) название банка
    "nativeName": "Banco Sabadell", // Локальное (национальное или региональное) название банка
    "currencies": [ // Массив с информацией о валютах, поддерживаемых банком
      {
        "id": 978, // Идентификатор валюты в платёжной платформе
        "alpha_3_4217": "EUR", // Буквенный код валюты в формате ISO-4217 alpha-3
        "number_3_4217": "978", // Цифровой код валюты в формате ISO-4217 alpha-3
        "exponent": 2 // Число дробных разрядов валюты
      }
    ]
  },
  {
    "id": 56641,
    "abbr": "T-BBVAES",
    "name": "BBVA",
    "nativeName": "BBVA",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": ,
    "abbr": "T-CAIXAPOP",
    "name": "Caixa Popular",
    "nativeName": "Caixa Popular",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]

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

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

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

Чтобы обеспечивать в таких случаях корректное уведомление мерчантов о состоянии платежей, в платёжной платформе ecommpay применяется процедура подтверждения зачисления средств получателю. При подключении метода Open Banking in Spain рекомендуется согласовывать с курирующим менеджером применение этой процедуры, а также перевод платежей, по которым получено подтверждение о том, что средства не зачислены, в статус 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 Spain со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. При этом следует учитывать, что в процессе проведения платежа пользователь последовательно перенаправляется к сервисам провайдера и банка, для чего от него требуется согласие и в некоторых случаях могут требоваться дополнительные сведения.

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

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



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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-spanish-banks",
   "payment_methods_options": {"online_spanish_banks": {"split_banks": true, "banks_id": [56611, 56621]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

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

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

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

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

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

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

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

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

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

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



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

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

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

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

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

    Кроме того, в некоторых случаях, в силу специфики метода, даже если в исходном запросе был указан номер счёта (International Bank Account Number, IBAN), он всё равно запрашивается дополнительно, через указание объекта account с параметром number в оповещении на уточнение.

    Кроме того, в некоторых случаях, с учётом специфики используемого банка, пользователю может требоваться указывать на стороне веб-сервиса номер счёта (International Bank Account Number, IBAN), в то время как в других случаях этот номер указывается пользователем на стороне провайдера или банка. При этом, в силу специфики метода, даже если номер счёта пользователя указывается в исходном запросе, он не учитывается при первичной обработке этого запроса и может быть запрошен отдельно, через указание объекта account с параметром number в оповещении на уточнение (вместе с указанием имени и фамилии пользователя, если они не были переданы).

    Подробнее об уточнении параметров — в статье Дополнение информации о платеже.

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

Таким образом, корректный запрос на оплату с применением метода Open Banking in Spain должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, идентификатор банка, 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":{
      "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":{
      "return": "http://example.com/return"
 }
}

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

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

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

Структурно в объект clarification_fields включаются объекты с заданным набором вложенных элементов (type, description, properties, required, errors) для описания каждого запрашиваемого объекта и параметра, при этом объект properties и массив required указываются в соответствии со спецификацией JSON Schema.

В структуру каждого объекта, включённого в объект clarification_fields, входят:

  • параметры type и description с указанием типа и описания объекта;
  • объект properties с информацией о параметрах, включённых в объект;
  • массив required со списком требуемых параметров;
  • массив errors с информацией о причинах запроса указанных параметров.

В рамках этой структуры объект properties и массив required указываются в соответствии со спецификацией JSON Schema, а в объектах массива errors приводятся параметры property, message и constraint для указания названий запрошенных параметров, поясняющих сообщений и описаний причин.

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

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

Рис. 15. Пример данных из оповещения о необходимости получения согласия пользователя
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}

После получения на стороне веб-сервиса согласия пользователя и запрошенных сведений каждый раз необходимо отправлять 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": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
Рис. 16. Пример набора данных для запроса на продолжение платежа
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}

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

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

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

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

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

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

Рис. 18. Пример данных из оповещения о проведении оплаты
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Spanish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "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=="
    }

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

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

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

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

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

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

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

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