Hong Kong Virtual Account
Обзор
Hong Kong Virtual Account — это платёжный метод для проведения оплат в Гонконге, в рамках которого пользователь переводит средства на виртуальный банковский счёт с помощью мобильного приложения банка. Оплаты осуществляются через Payment Page и Gate.
Характеристика
Тип платёжного метода | банковские платежи |
---|---|
Платёжные инструменты | банковские счета |
Регионы использования | HK |
Валюты платежей | HKD, CNY |
Конвертация валют | – |
Оплаты | + |
Выплаты | – |
Оплаты по сохранённым данным | – |
Полные возвраты | – |
Частичные возвраты | – |
Опротестования | – |
Особенности | при оплате пользователь может указывать сумму, отличную от суммы в запросе; информация о реагировании на такие случаи представлена далее |
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием Hong Kong Virtual Account задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства провайдера.
Основные операции
Интерфейсы | Суммы, HKD | Время* | ||||||
---|---|---|---|---|---|---|---|---|
Payment Page | CMS Plug-ins | Gate | Dashboard | минимум | максимум | базовое | предельное | |
Оплаты | + | – | + | – | – | 4 000 000,00 | – | – |
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.
Сценарии использования
При работе с методом Hong Kong Virtual Account для проведения оплаты пользователю необходимо выполнить перевод на виртуальный банковский счёт через приложение банка.
Рис.: Оплата через Payment Page
Рис.: Оплата через Gate
Обработка некорректных платёжных данных
При работе с этим методом вся необходимая для оплаты информация представляется пользователю в инструкции. Вместе с тем, поскольку пользователь совершает перевод через сервис своего банка, он может преднамеренно или случайно нарушить правила заполнения данных. В таком случае платёж признаётся проведённым и в итоговом оповещении о проведении этого платежа содержится информация о сумме, которая была указана пользователем при оплате, независимо от того, совпадает ли она с суммой в запросе, после чего разрешение этой ситуации осуществляется на стороне мерчанта.
Предположим, что для инициирования платежа был использован следующий запрос через Gate с указанием суммы 300,00 HKD:
Рис.: Пример данных из запроса
{ "general": { "project_id": 1234567, "payment_id": "abc12345", "signature": "123abc...456789" }, "customer": { "id": "123" "ip_address": "1.1.1.1" }, "payment": { "amount": 30000, "currency": "HKD" } }
Если пользователь указал при оплате сумму 250,00 HKD и платёж был успешно обработан на стороне провайдера и платёжной платформы, то от платформы к веб-сервису отправляется оповещение следующего вида с фактической суммой, указанной пользователем. При этом на стороне мерчанта необходимо иметь возможность обработать такое оповещение, несмотря на отличие фактической суммы платежа от исходной суммы в запросе.
Рис.: Пример данных из оповещения
{ "project_id": 3514, "payment": { "id": "EP0c8a-960e", "type": "purchase", "status": "success", "date": "2021-02-10T10:10:14+0000", "method": "hk-va", "sum": { "amount": 25000, "currency": "HKD" }, "description": "" }, "operation": { "id": 360, "type": "sale", "status": "success", "date": "2021-02-10T10:10:14+0000", "created_date": "2021-02-10T10:09:34+0000", "request_id": "cca222750e99b05bc6656ec...000001", "sum_initial": { "amount": 25000, "currency": "HKD" }, "sum_converted": { "amount": 25000, "currency": "HKD" }, "code": "0", "message": "Success", "provider": { "id": 5171, "payment_id": "16129...9796", "auth_code": "", "date": "2021-02-10T10:09:57+0000" } }, "signature": "9sHwkk4fbhwQg3PH/8ShWtbqgBZEcfaC+HnVrQe6DFFCQX14w==" }
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.
Оплаты через Payment Page
Общая информация
Для оплаты через Payment Page с использованием метода Hong Kong Virtual Account со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате оплаты. При этом метод Hong Kong Virtual Account можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжных методов). Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Payment Page
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- Осуществляется формирование Payment Page согласно настройкам проекта и параметрам вызова.
- Пользователю отображается сформированная платёжная форма.
- Пользователь выбирает для оплаты метод Hong Kong Virtual Account.
- Запрос на проведение оплаты через провайдера поступает в платёжную платформу.
- Выполняется дальнейшая обработка запроса.
- Данные для отображения платёжной инструкции пользователю передаются к Payment Page.
- Пользователю отображается платёжная инструкция.
- Пользователь выполняет необходимые действия для завершения оплаты.
- На стороне сервиса провайдера выполняется обработка платежа.
- От сервиса провайдера к платёжной платформе направляется результат оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От платёжной платформы к Payment Page отправляется информация о результате проведения оплаты.
- Информация о результате оплаты отображается пользователю на Payment Page.
Информация о формате запросов и параметрах вызова Payment Page при работе с Hong Kong Virtual Account, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API см. в разделе Описание Payment Page API.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода Hong Kong Virtual Account необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- customer_id — идентификатор пользователя в рамках проекта;
- payment_currency — валюта платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа, указанная в дробных единицах валюты.
- Валютой платежа может быть только HKD или CNY.
- Для предварительного выбора метода Hong Kong Virtual Account необходимо указывать код платёжного метода в параметре force_payment_method —
hk-va
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
- После определения всех параметров необходимо составить подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода Hong Kong Virtual Account должен содержать идентификаторы проекта, пользователя и платежа, валюту и сумму платежа, а также подпись:
EPayWidget.run( { payment_id: 'X03936', payment_amount: 10000, payment_currency: 'HKD', project_id: '12345', customer_id: '123' signature: "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU...ZhkIQg==" } )
Формат оповещений
Для оповещений о результатах оплат с применением метода Hong Kong Virtual Account используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 123
для пользователя customer1
была успешно проведена оплата в размере 100,00 HKD
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 123, "payment": { "id": "12345678", "type": "purchase", "status": "success", "date": "2021-04-26T08:40:29+0000", "method": "hk-va", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 6301000010721, "type": "sale", "status": "success", "date": "2021-04-26T08:40:29+0000", "created_date": "2021-04-26T08:39:53+0000", "request_id": "faac1f505a3e188fb384d7eabc735335b32af288...006302", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "0", "message": "Success", "provider": { "id": 5171, "payment_id": "", "auth_code": "" } }, "signature": "tqmkAb32XGHYglWq3Nm7XD7Yq21fV21dcGBMPb7/ddzuts...qoumh8dQw==" } }
В следующем примере оплата была отклонена.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 0123, "payment": { "id": "123456789", "type": "purchase", "status": "decline", "date": "2021-04-26T08:40:29+0000", "method": "hk-va", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "customer": { "id": "customer1234" }, "operation": { "id": 5205000010711, "type": "sale", "status": "decline", "date": "2021-04-26T08:40:29+0000", "created_date": "2021-04-26T08:39:53+0000", "request_id": "9b430e9f97d5fa903985e482242f6638...0005206", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "20000", "message": "General decline", "provider": { "id": 5171, "payment_id": "", "auth_code": "" } }, "signature": "+a9OY3rEEhMlPpR54LJoQa...2HfVTKJO5LeUmFUDtfA==" } }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
Оплаты через Gate
Общая информация
Для оплаты через Gate с использованием метода Hong Kong Virtual Account со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Отобразить пользователю инструкцию для оплаты.
- Принять оповещение от платежной платформы ecommpay о результате оплаты.
Полная схема проведения оплаты представлена далее.
Рис.: Проведение оплаты через Gate
- Пользователь на стороне веб-сервиса инициирует оплату через провайдера.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
- Выполняется дальнейшая обработка запроса.
- От платёжной платформы к веб-сервису направляется оповещение с данными для отображения платёжной инструкции пользователю.
- Пользователю отображается платёжная инструкция.
- Пользователь выполняет необходимые действия для завершения оплаты.
- На стороне сервиса провайдера выполняется обработка платежа.
- От сервиса провайдера к платёжной платформе направляется уведомление о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- От веб-сервиса пользователю направляется результат оплаты.
Информация о формате запросов и параметрах инициации оплат методом Hong Kong Virtual Account через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API см. в разделе Работа с API.
Формат запросов
При работе с запросами на оплаты с применением метода Hong Kong Virtual Account необходимо учитывать следующее:
- Должен использоваться запрос к конечной точке
/v2/payment/banks/hk-va/sale
, отправляемый методом POST. Этот запрос относится к группе запросов /v2/payment/banks/{payment_method}/sale. - В запросе должны использоваться следующие объекты и параметры:
- general — основные сведения:
- project_id — идентификатор проекта,
- payment_id — идентификатор платежа,
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- customer — сведения о пользователе:
- ip_address — используемый IP-адрес;
- id — идентификатор пользователя в рамках проекта;
- payment — сведения о платеже:
- amount — сумма платежа, указанная в дробных единицах валюты;
- currency — валюта платежа в формате ISO-4217 alpha-3.
- general — основные сведения:
- Валютой платежа может быть только HKD или CNY.
- Дополнительно могут использоваться все параметры, указанные в спецификации.
Таким образом, корректный запрос на оплату с применением метода Hong Kong Virtual Account должен содержать идентификаторы проекта, пользователя и платежа, IP-адрес пользователя, валюту и сумму платежа, а также подпись:
Рис.: Пример запроса на оплату
{ "general": { "project_id": 1234567, "payment_id": "abc12345", "signature": "123abc...456789" }, "customer": { "id": "123", "ip_address": "1.1.1.1" }, "payment": { "amount": 10000, "currency": "HKD" } }
Форматы данных для отображения платёжной инструкции
Для отображения платёжной инструкции необходимо принять и обработать оповещение от платёжной платформы, содержащее данные о платеже в массиве display_data, и отобразить пользователю платёжную инструкцию.
Помимо текста инструкции рекомендуется отобразить пользователю информация о времени, отведённом на выполнение необходимых для проведения оплаты действий. Если пользователь не подтверждает платёж до истечения указанного срока, выдаётся сообщение об ошибке.
Далее приведён текст инструкции для отображения пользователю:
Текст инструкции на китайском языке (традиционное письмо) | Текст инструкции на английском языке |
---|---|
付款詳情 | Payment Details |
銀行名稱: DBS Bank (Hong Kong) Limited | Bank Name: DBS Bank (Hong Kong) Limited |
帳戶持有人姓名:DOLLARSMART GLOBAL PTE. LTD. LTD. | Account Holder name: DOLLARSMART GLOBAL PTE. LTD. |
銀行帳號:{{va_number}} | Bank Account number: {{va_number}} |
轉帳金額: {{amount}} | Transfer amount: {{amount}} |
貨幣:HKD | Currency: HKD |
失效日期 | Expiration date |
如何支付 | How to pay |
1) 打開您的銀行應用程序,並從您的帳戶開始新的轉帳。 | 1) Open your banking app and start a new transfer from your account. |
2) 選擇“DBS BANK(HONG KONG)LIMITED”作為收款銀行。 | 2) Select "DBS BANK (HONG KONG) LIMITED" as a payee bank. |
3) 輸入帳戶持有人姓名:“DOLLARSMART GLOBAL PTE. LTD.” | 3) Enter account holder’s name: "DOLLARSMART GLOBAL PTE. LTD." |
4) 輸入銀行帳號。 | 4) Enter the bank account number. |
5) 如有需要,請選擇HKD貨幣和付款日期。 | 5) Select HKD currency and payment date if necessary. |
6) 輸入要支付的金額。 | 6) Enter the amount to be paid. |
7)選擇“CONFIRM”以繼續轉帳。 | 7) Select "CONFIRM" to proceed with the transfer. |
確認後,付款處理時間少於1分鐘。 | Payment processing takes less than 1 minute after confirmation. |
Массив display_data содержит следующие параметры:
- type — тип передаваемых данных (в значении всегда передаётся
add_info
); - title — название передаваемых данных, которые необходимо отобразить пользователю (в значении всегда передаётся
virtual_account_number
); - data — номер созданного виртуального банковского счёта.
Далее приведён фрагмент оповещения, содержащего данные для отображения пользователю.
"display_data": [
{
"type": "add_info",
"title": "virtual_account_number",
"data": "1213323442...523521424"
}
]
Формат оповещений
Для оповещений о результатах оплат с применением метода Hong Kong Virtual Account используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 456
от пользователя customer1
была успешно проведена оплата в размере 100,00 HKD
.
Рис.: Пример оповещения о проведении оплаты
{ "project_id": 456, "payment": { "id": "12345678", "type": "purchase", "status": "success", "date": "2021-04-26T08:40:29+0000", "method": "hk-va", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "customer": { "id": "customer1" }, "operation": { "id": 6301000010721, "type": "sale", "status": "success", "date": "2021-04-26T08:40:29+0000", "created_date": "2021-04-26T08:39:53+0000", "request_id": "faac1f505a3e188fb384d7eabc735335b32af288...006302", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "0", "message": "Success", "provider": { "id": 5171, "payment_id": "", "auth_code": "" } }, "signature": "tqmkAb32XGHYglWq3Nm7XD7Yq21fV21dcGBMPb7/ddzuts...qoumh8dQw==" } }
В следующем примере оплата была отклонена.
Рис.: Пример оповещения об отказе в проведении оплаты
{ "project_id": 0123, "payment": { "id": "123456789", "type": "purchase", "status": "decline", "date": "2021-04-26T08:40:29+0000", "method": "hk-va", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "customer": { "id": "customer1234" }, "operation": { "id": 5205000010711, "type": "sale", "status": "decline", "date": "2021-04-26T08:40:29+0000", "created_date": "2021-04-26T08:39:53+0000", "request_id": "9b430e9f97d5fa903985e482242f6638...0005206", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "20000", "message": "General decline", "provider": { "id": 5171, "payment_id": "", "auth_code": "" } }, "signature": "+a9OY3rEEhMlPpR54LJoQa...2HfVTKJO5LeUmFUDtfA==" } }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
Анализ результатов проведения платежей
Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода Hong Kong Virtual Account доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.
Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей на вкладке Analytics.
Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:
- Dashboard позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
- Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.
С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ecommpay.