Hong Kong FPS QR
Обзор
Введение
Hong Kong FPS QR — метод, позволяющий проводить платежи в гонконгских долларах и китайских юанях с использованием банковских счетов в Гонконге. Для работы с этим методом могут использоваться различные приложения, поддерживающие работу со стандартом QRIS (Quick Response Code Indonesian Standard). Для этого метода в платёжной платформе ecommpay поддерживаются оплаты.
В этой статье представлена информация о работе с методом Hong Kong FPS QR: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | платежи с помощью QR-кодов |
---|---|
Платёжные инструменты | банковские счета |
Регионы использования | HK |
Валюты платежей | HKD, CNY |
Конвертация валют | – |
Разовые оплаты | + |
Повторяемые оплаты | – |
Полные возвраты | – |
Частичные возвраты | – |
Выплаты | – |
Опротестования | – |
Особенности | – |
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием метода Hong Kong FPS QR задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса провайдера.
Основные операции
Для проведения платежей и выполнения операций с использованием метода Hong Kong FPS QR могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок). При этом, независимо от используемых интерфейсов, для этого метода характерны следующие ограничения.
При работе с методом Hong Kong FPS QR, независимо от используемых интерфейсов, актуальны следующие ограничения.
Суммы, HKD | ||
---|---|---|
минимум | максимум | |
Оплаты | – | 10 000,00 |
Сценарии использования
Проведение оплат с использованием метода Hong Kong FPS QR осуществляется со сканированием пользователем QR-кода с использованием банковского приложения.
Пользовательский сценарий оплаты через Payment Page (в базовом варианте с выбором пользователем метода и перенаправлением с итоговой страницы платёжной формы к веб-сервису) выглядит следующим образом.
Общие сценарии проведения оплат можно представить следующим образом.
Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом Hong Kong FPS QR соответствуют специфике этих возможностей.
Оплаты через Payment Page
Общая информация
Для проведения оплаты через Payment Page с использованием метода Hong Kong FPS QR со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
- Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
- Пользователю отображается платёжная форма.
- Пользователь выбирает для оплаты метод Hong Kong FPS QR.
- В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Hong Kong FPS QR.
- В платёжной платформе обеспечиваются обработка полученного запроса.
- Данные для отображения платёжной инструкции пользователю передаются к Payment Page.
- Пользователю отображается платёжная инструкция.
- Пользователь выполняет необходимые действия для оплаты согласно инструкции.
- В сервисе провайдера выполняется обработка платежа.
- От сервиса провайдера к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page направляется информация о результате оплаты.
- Информация о результате оплаты отображается пользователю на Payment Page.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Hong Kong FPS QR через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода Hong Kong FPS QR необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;payment_currency
— код валюты платежа в формате ISO-4217 alpha-3;payment_amount
— сумма платежа в дробных единицах валюты;customer_id
— идентификатор пользователя в рамках проекта.
- Должен использоваться базовый минимум параметров:
project_id
,payment_id
,payment_currency
,payment_amount
,customer_id
. - Валютой платежа может быть только HKD или CNY.
- Для предварительного выбора метода Hong Kong FPS QR необходимо указывать код платёжного метода
hk-qr
в параметреforce_payment_method
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода Hong Kong FPS QR должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор пользователя и подпись.
{ "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "HKD", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
{ "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "HKD", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Формат оповещений
Для оповещений о результатах оплат с применением метода Hong Kong FPS QR используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 123
была проведена оплата в размере 100,00 HKD
.
{ "project_id": 123, "payment": { "id": "123123123", "type": "purchase", "status": "success", "date": "2021-04-26T08:40:29+0000", "method": "hk-qr", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 5205000010711, "type": "sale", "status": "success", "date": "2021-04-26T08:40:29+0000", "created_date": "2021-04-26T08:39:53+0000", "request_id": "23fdebfc248b0676209a5e0694487738a...08525", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "0", "message": "Success", "provider": { "id": 5161, "payment_id": "", "auth_code": "" } }, "signature": "Dj2MN6VS9yDGrRAnJ5sMRnr/J4C7nLN08qIVqFA7pTlw==" } }
В следующем примере оповещение свидетельствует об отклонённой оплате.
{ "project_id": 0123, "payment": { "id": "12341234", "type": "purchase", "status": "decline", "date": "2021-04-26T08:40:29+0000", "method": "hk-qr", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 4991000010711, "type": "sale", "status": "decline", "date": "2021-04-26T08:40:29+0000", "created_date": "2021-04-26T08:39:53+0000", "request_id": "3d12732e00fb397dbe99ad86604992", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "20000", "message": "General decline", "provider": { "id": 5161, "payment_id": "", "auth_code": "" } }, "signature": "LbcKUUDELHz8wxx56WCT0T/W00cC6rwYqSekS6Kg==" } }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
- Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
Для проведения оплаты через Gate с использованием метода Hong Kong FPS QR со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять промежуточное оповещение от платёжной платформы и отобразить платёжную инструкцию пользователю.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
- Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Hong Kong FPS QR.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
- В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
- В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров).
- От платёжной платформы к веб-сервису направляется оповещение с данными для отображения платёжной инструкции пользователю.
- Пользователю на стороне веб-сервиса отображается платёжная инструкция.
- Пользователь выполняет необходимые действия для оплаты согласно инструкции.
- В сервисе провайдера выполняется обработка платежа.
- От сервиса провайдера к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Hong Kong FPS QR через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на оплаты с применением метода Hong Kong FPS QR необходимо учитывать следующее:
- Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/banks/hk-qr/sale
. Эта точка относится к группе /v2/payment/banks/{payment_method}/sale. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма платежа в дробных единицах валюты;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемого платежа.
- Валютой платежа может быть только HKD или CNY.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на оплату с применением метода Hong Kong FPS QR должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, а также подпись.
{ "general": { "project_id": 383000, "payment_id": "abc123456", "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9...xI5vOA7w==" }, "customer": { "ip_address": "192.0.2.0", "id": "123" }, "payment": { "amount": 10000, "currency": "HKD" } }
{ "general": { "project_id": 383000, "payment_id": "abc123456", "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9...xI5vOA7w==" }, "customer": { "ip_address": "192.0.2.0", "id": "123" }, "payment": { "amount": 10000, "currency": "HKD" } }
Форматы данных для отображения платёжной инструкции
Для отображения платёжной инструкции необходимо принять и обработать оповещение от платёжной платформы, содержащее данные о платеже в массиве display_data
, и отобразить пользователю платёжную инструкцию.
Помимо текста инструкции рекомендуется отобразить пользователю информацию о времени, отведённом на выполнение необходимых для проведения оплаты действий. Если пользователь не подтверждает платёж до истечения указанного срока, выдаётся сообщение об ошибке.
Далее приведён текст инструкции для отображения пользователю:
Текст инструкции на китайском языке (традиционное письмо) | Текст инструкции на английском языке |
---|---|
二維碼有效期 | QR code expiration date |
請下載二維碼並在網上銀行應用程序的二維碼掃描功能中使用 | Please download the QR code and use it in the QR scan function of your online banking application |
此二維碼僅供一次性掃描 | For one-time use only |
Массив display_data
содержит следующие параметры:
type
— тип передаваемых данных (в значении всегда передаётсяqr_data
);title
— название передаваемых данных, которые необходимо отобразить пользователю (в значении всегда передаётсяQR code
);data
— строка с закодированным изображением QR-кода.
Далее приведён фрагмент оповещения, содержащего данные для отображения пользователю.
"display_data": [ { "type": "qr_data", "title": "QR code", "data": "1213323442...523521424" } ]
Формат итоговых оповещений
Для оповещений о результатах оплат с применением метода Hong Kong FPS QR используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 456
была проведена оплата в размере 100,00 HKD
.
{ "project_id": 456, "payment": { "id": "123123123", "type": "purchase", "status": "success", "date": "2021-04-26T08:40:29+0000", "method": "hk-qr", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 5205000010711, "type": "sale", "status": "success", "date": "2021-04-26T08:40:29+0000", "created_date": "2021-04-26T08:39:53+0000", "request_id": "23fdebfc248b0676209a5e0694487738a...08525", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "0", "message": "Success", "provider": { "id": 5161, "payment_id": "", "auth_code": "" } }, "signature": "Dj2MN6VS9yDGrRAnJ5sMRnr/J4C7FPOl8...nLN08qIVqFA7pTlw==" } }
В следующем примере оповещение свидетельствует об отклонённой оплате.
{ "project_id": 0123, "payment": { "id": "12341234", "type": "purchase", "status": "decline", "date": "2021-04-26T08:40:29+0000", "method": "hk-qr", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 4991000010711, "type": "sale", "status": "decline", "date": "2021-04-26T08:40:29+0000", "created_date": "2021-04-26T08:39:53+0000", "request_id": "3d12732e00fb397dbe99ad866e05ecfc...004992", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "20000", "message": "General decline", "provider": { "id": 5161, "payment_id": "", "auth_code": "" } }, "signature": "LbcKUUDELHz8wxx56WCT0T/W00cC6rEAXax7u1kwYqSekS6Kg==" } }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу Hong Kong FPS QR, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.