Open Banking in Portugal

Введение

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

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

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

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

Схема работы

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

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

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

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

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

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

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

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

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

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

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

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

[
  {
    "id": 6631, // Индентификатор банка
    "abbr": "NBDA", // Служебное название банка в платформе (или его аббревиатура)
    "name": "NOVO BANCO DOS ACORES", // Основное (международное) название банка
    "nativeName": "NOVO BANCO DOS ACORES", // Локальное (национальное или региональное) название банка
    "currencies": [ // Массив с информацией о валютах, поддерживаемых банком
      {
        "id": 978, // Идентификатор валюты в платёжной платформе
        "alpha_3_4217": "EUR", // Буквенный код валюты в формате ISO-4217 alpha-3
        "number_3_4217": "978", // Цифровой код валюты в формате ISO-4217 alpha-3
        "exponent": 2 // Число дробных разрядов валюты
      }
    ]
  },
  {
    "id": 6661,
    "abbr": "BANCO-BPI",
    "name": "Banco BPI",
    "nativeName": "Banco BPI",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 6331,
    "abbr": "BST-TOTA",
    "name": "Banco Santander Totta",
    "nativeName": "Banco Santander Totta",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]

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

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

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

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

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

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

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

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

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

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

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

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

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_portuguese_banks), а содержимым — параметр split_banks со значением true. При этом в записи такого объекта все вложенные символы " (U+0022) должны экранироваться с помощью предшествующих им символов \ (U+005C).

      "payment_methods_options": "{\"online_portuguese_banks\": {\"split_banks\": true}}"

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

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

      "payment_methods_options": "{\"online_portuguese_banks\": {\"split_banks\": true}}",
      "force_payment_group": "openbanking"

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

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

      "force_payment_method": "online-portuguese-banks"

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

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

      "payment_methods_options": "{\"online_portuguese_banks\": {\"split_banks\": true, \"banks_id\": [6651, 6641]}}",
      "force_payment_method": "online-portuguese-banks"

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

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

      "payment_methods_options": "{\"online_portuguese_banks\": {\"split_banks\": true, \"banks_id\": [6651]}}",
      "force_payment_method": "online-portuguese-banks"

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

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

Таким образом, корректный запрос на открытие платёжной формы с применением метода Open Banking in Portugal должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, 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=="
}

{
   "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-portuguese-banks",
   "payment_methods_options": {"online_portuguese_banks": {"split_banks": true, "banks_id": [6641, 6651]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Portuguese 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=="
    }

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

 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Portuguese 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 также могут быть полезны следующие материалы:

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

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

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

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

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

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

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

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

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

1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/portugal/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 Portugal должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, идентификатор банка, 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"
 }
}

{
    "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 Portugal для проведения каждой оплаты требуется получать дополнительное согласие пользователя и, если актуально, дополнительные сведения о нём. Для этого в процессе проведения каждой оплаты от платёжной платформы к веб-сервису направляется промежуточное оповещение с объектом 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.

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

{
  "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"
    }
  }
}

{
  "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 Portugal необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data включаются следующие объекты и параметры:

• body — объект с данными для отправки в теле запроса;
• method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
• url — параметр со ссылкой для перенаправления.

"redirect_data": {
        "method": "POST",
        "body": [],
        "encrypted": [],
        "url": "https://web-app.example.com/app/request-token/rq:3R123"
    }

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

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

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

 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Portuguese 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=="
    }

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

 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Portuguese 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 также могут быть полезны следующие материалы:

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