Open Banking - Оплата 2: с запросом согласия пользователя и отображением платежной инструкции

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

Чтобы выполнить оплату через Payment Page с использованием метода Open Banking:

1. Отправьте запрос с нужными параметрами и подписью на рабочий URL-адрес платежной платформы Benker.
2. Примите от платежной платформы Benker оповещение (callback) с результатом оплаты.

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

Запрос

В запросе на открытие страницы оплаты с использованием метода Open Banking укажите необходимые параметры:

Вот пример параметров из запроса на открытие страницы оплаты с использованием виджета EPayWidget:

EPayWidget.run(
	{
		project_id: 1234,
		payment_id: 'payment_47',
		customer_id: 'customer_123',
		customer_first_name: 'John',
		customer_last_name: 'Doe',
		customer_email: 'johndoe@example.com',
		customer_account_number: 'DE89370400440532013000',
		payment_currency: 'EUR',
		payment_amount: 10000,
		force_payment_method: 'open-banking',
		merchant_return_url: 'http://example.com/return',
		signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=='
	}
)

Отображение иконок банков на странице оплаты

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

Метод Open Banking позволяет вам определить, как отображать значки банков на странице оплаты:

• Выбор банка в два шага Этот вариант используется по умолчанию. Пользователь выбирает банк в два шага: сначала он выбирает Open Banking среди прочих методов, а затем — конкретный банк среди доступных в методе, вводя название банка или номер счета пользователя IBAN (International Bank Account Number).
• Отображение банков только одного метода Чтобы отобразить на странице оплаты только банки (без других платежных методов), доступные в методе Open Banking, передайте в запросе на открытие страницы оплаты код платежного метода open-banking в параметре force_payment_method.
• Принудительный выбор банка Если в запросе на открытие страницы оплаты передать код платежного метода open-banking в параметре force_payment_method вместе с параметром payment_extra_param и идентификатором одного из банков в параметре account_bank_id, то страницы выбора метода и банка будут пропущены, а пользователь будет сразу перенаправлен в сервис банка. Информация об идентификаторах банков, доступных в этом методе, указана в соответствующем разделе Банки для оплаты.
  Прим.: Значение параметра payment_extra_param необходимо согласовать со специалистами технической поддержки Benker.

  Далее приведен пример данных из запроса на открытие страницы оплаты с предварительно выбранным банком через виджет EPayWidget.

  EPayWidget.run(
  	{
  		project_id: 1234,
  		payment_id: 'payment_47',
  		customer_id: 'customer_123',
  		customer_first_name: 'John',
  		customer_last_name: 'Doe',
  		customer_email: 'johndoe@example.com',
  		payment_currency: 'EUR',
  		payment_amount: 10000,
  		force_payment_method: 'open-banking',
  		payment_extra_param: 'deeplink', 
  		account_bank_id: '12345',
  		signature: 'kUi2x9dKHA5VNU0FY...vySO/RLCv1htT4DqtVUkDJrOcZzUCwX6Rek7pZhkIQg=='
  	}
  )

Оповещение (callback)

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

Вот пример тела оповещения с информацией об успешно выполненной оплате:

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "method": "open-banking",
        "sum": {
            "amount": 10000,
            "currency": "EUR"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "sale",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 10000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Вот пример тела оповещения с информацией об отклоненной оплате.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "method": "open-banking",
        "sum": {
            "amount": 10000,
            "currency": "EUR"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "sale",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 10000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "EUR"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

• Организация взаимодействия
• Модель проведения платежей
• Работа с подписью к данным
• Статусы операций и коды ответов

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

Чтобы выполнить оплату через Gate с использованием метода Open Banking:

1. Отправьте запрос с нужными параметрами и подписью на рабочий URL-адрес платежной платформы Benker.
2. Получите от платежной платформы оповещение (callback) с информацией о том, какие данные вы должны передать платежной платформе.
3. Отправьте запрос с этими данными платежной платформе Benker.
4. Примите от платежной платформы Benker оповещение (callback) с результатом оплаты.

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

Запрос

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

Вот пример тела запроса на оплату с использованием метода Open Banking:

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com",
        "language": "EN"
    },
    "account": {
        "bank_id": "593123456789"
    },
    "payment": {
        "currency": "EUR",
        "amount": 10000
    }
}

Отображение платежной инструкции пользователю

Получив и обработав запрос на оплату, платежная платформа направит вам оповещение (callback) с платежной инструкцией для отображения пользователю.

Чтобы отобразить пользователю платежную инструкцию, используйте информацию из массива display_data.

{
    "type": "qr_img",
    "title": "qr_code_img",
    "data": "data:image/png;base64,iVBORU6ZMKV/syvW"
}

{
    "type": "deep_link",
    "title": "deep_link",
    "data": "https://example.com/"
}

{
    "type": "add_info",
    "title": "pre_authorization_flow",
    "data": "pre_authorization_flow"
}

{
    "type": "add_info",
    "title": "authorization_flow",
    "data": "authorization_flow"
}

{
    "type": "add_info",
    "title": "psu_consent_text",
    "data": "test consent"
}

Далее представлен фрагмент оповещения с массивом display_data.

"display_data": [
    {
        "type": "qr_img",
        "title": "qr_code_img",
        "data": "data:image/png;base64,iVBORU6ZMKV/syvW"
    },
    {
        "type": "deep_link",
        "title": "deep_link",
        "data": "https://example.com/"
    },
    {
        "type": "add_info",
        "title": "pre_authorization_flow",
        "data": "pre_authorization_flow"
    },
    {
        "type": "add_info",
        "title": "authorization_flow",
        "data": "authorization_flow"
    },
    {
        "type": "add_info",
        "title": "psu_consent_text",
        "data": "test consent"
    }
]

Промежуточные оповещения

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

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

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

{
  "clarification_fields": {
	"customer": {
		"type": "object",
		"description": "",
		"properties": {
		  "last_name": {
		  "type": "string",
		  "description": "Customer's last name"
// Фамилия пользователя - один из возможных параметров при запросе дополнительных сведений
		},
	    }
	 },
	"account": {
		 "type": "object",
		 "description": "",
		 "properties": {
			 "number": {
			 "type": "string",
			 "description": "Customer's International Bank Account Number."
// Номер счета пользователя - один из возможных параметров при запросе дополнительных сведений
			 }
		 }
	 }
  }
 }

Отправка дополнительных сведений о пользователей в платежную платформу

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

Вот пример данных из запроса для передачи в платежную платформу информации о пользователе:

{
	"general": {
		"project_id": 1234,
		"payment_id": "payment_47",
		"signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
		},
	"additional_data": {
		"customer": {
			"last_name":"Doe"
		},
		"account": {
			"number":"1234567890123"
		}
	 }
}

Оповещение (callback)

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

Вот пример тела оповещения с информацией об успешно выполненной оплате:

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "method": "open-banking",
        "sum": {
            "amount": 10000,
            "currency": "EUR"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "sale",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 10000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Вот пример тела оповещения с информацией об отклоненной оплате.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "method": "open-banking",
        "sum": {
            "amount": 10000,
            "currency": "EUR"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "sale",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 10000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "EUR"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

• Организация взаимодействия
• Модель проведения платежей
• Работа с подписью
• Статусы операций и коды ответов

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

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

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

Запрос списка банков

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

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

{
	"general": {
		"project_id": 200,
		"payment_id": "ORDER_155860015",
		"signature": "K6jll2ym+PtOb3ocZtr345st...=="
	},
	"payment": {
		"amount": 10000,
		"currency": "EUR"
	},
	"account": {
		"country":"GB"
	}
}

[
	{
		"minAmount": 100, // Минимальная сумма платежа (в дробных единицах валюты)
		"maxAmount": 1000, // Максимальная сумма платежа (в дробных единицах валюты)
		"limitCurrency": "EUR", // Код валюты в формате ISO-4217 alpha-3, в которой указаны лимиты (minAmount и maxAmount)
		"id": 123, // Индентификатор банка
		"abbr": "EXB", // Служебная аббревиатура банка (для внутреннего применения)
		"name": "Example Bank", // Основное название банка
		"nativeName": "Example Bank", // Локальное название банка
		"currencies": [ // Массив с информацией о валютах, поддерживаемых банком
			{
				"id": 123, // Идентификатор валюты в платежной платформе
				"alpha_3_4217": "EUR", // Буквенный код валюты платежа в формате ISO-4217 alpha-3
				"number_3_4217": "123", // Цифровой код валюты платежа в формате ISO-4217 alpha-3
				"currency_type": "fiat", // Тип валюты
				"exponent": 2 // Число дробных разрядов валюты
			}
		]
	}
]

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

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

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

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

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

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

• success — при получении со стороны провайдера подтверждения того, что средства зачислены. В этом случае платежу присваивается статус success и к вашей системе отправляется итоговое оповещение с информацией о результате оплаты.
• decline — при получении со стороны провайдера информации о том, что средства не зачислены, либо при отсутствии со стороны провайдера информации о зачислении средств по истечении установленного срока (который по умолчанию составляет 7 дней и может быть изменен через обращение к специалистам технической поддержки Benker).

  В таких случаях, с учетом свойств проекта на стороне платежной платформы, выполняется один из двух сценариев:

  • Формируется операция reversal и к вашей системе последовательно отправляются соответствующие оповещения: промежуточное, с информацией о том, что средства не были зачислены, и итоговое, с информацией о возврате средств и переводе платежа в статус reversed.
  • Платеж переводится в статус decline и к вашей системе направляется итоговое оповещение с информацией об отклонении оплаты.

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

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