Open Banking in Sweden

Введение

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

В платёжной платформе ecommpay поддерживаются оплаты методом Open Banking in Sweden.

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

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

Схема работы

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

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

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

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

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

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

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

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

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

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

Поскольку со временем состав доступных банков может меняться, дляДля получения актуальной информации о доступных банках рекомендуется использовать POST-запросы к конечной точке /v2/info/banks/sweden/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": "SEK"
  }
}

[
  {
    "id": 5121, // Индентификатор банка
    "abbr": "NORDEA-SWEDEN", // Служебная аббревиатура банка (для внутреннего применения)
    "name": "Nordea Bank", // Основное название банка
    "nativeName": "Nordea Bank", // Локальное название банка
    "currencies": [ // Массив с информацией о валютах, поддерживаемых банком
      {
        "id": 978, // Идентификатор валюты в платёжной платформе
        "alpha_3_4217": "EUR", // Буквенный код валюты платежа в формате ISO-4217 alpha-3
        "number_3_4217": "978", // Цифоровой код валюты платежа в формате ISO-4217 alpha-3
        "exponent": 2 // Число дробных разрядов валюты
      }
    ]
  },
  {
    "id": 5161,
    "abbr": "SWEDBANK-SWEDEN",
    "name": "Swedbank",
    "nativeName": "Swedbank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 55401,
    "abbr": "ALANDSBANKEN",
    "name": "Alandsbanken",
    "nativeName": "Alandsbanken",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]

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

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

Для проведения оплаты через Payment Page с использованием метода Open Banking in Sweden со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      "force_payment_method": "online-swedish-banks"

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

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

      "payment_methods_options": "{\"online_swedish_banks\": {\"split_banks\": true, \"banks_id\": [5151, 5161]}}",
      "force_payment_method": "online-swedish-banks"

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

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

      "payment_methods_options": "{\"online_swedish_banks\": {\"split_banks\": true, \"banks_id\": [5151]}}",
      "force_payment_method": "online-swedish-banks"

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

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

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "SEK",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "SEK",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "SEK",
   "customer_id": "customer1",
   "force_payment_method": "online-swedish-banks",
   "payment_methods_options": {"online_swedish_banks": {"split_banks": true, "banks_id": [5161, 5151]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Swedish Banks",
            "sum": {
                "amount": 1000,
                "currency": "SEK"
            },
            "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": "SEK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "SEK"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }

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

 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Swedish Banks",
            "sum": {
                "amount": 1000,
                "currency": "SEK"
            },
            "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": "SEK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "SEK"
            },
            "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 Sweden со стороны веб-сервиса необходимо:

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

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

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

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

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

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

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

{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "SEK"
      },
    "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"
 }
}

{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "SEK"
      },
    "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 Sweden необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект 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 Sweden используется типовой формат, описание которого представлено в статье Оповещения(подробнее).

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

 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Swedish Banks",
            "sum": {
                "amount": 1000,
                "currency": "SEK"
            },
            "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": "SEK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "SEK"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }

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

 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Swedish Banks",
            "sum": {
                "amount": 1000,
                "currency": "SEK"
            },
            "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": "SEK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "SEK"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }

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

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

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