Hong Kong Virtual Account
Обзор
Введение
Hong Kong Virtual Account — метод, позволяющий проводить платежи в гонконгских долларах и китайских юанях с использованием банковских счетов в Гонконге. В рамках оплат этим методом пользователь переводит средства на виртуальный банковский счёт с помощью мобильного приложения банка Для этого метода в платёжной платформе ecommpay поддерживаются оплаты.
В этой статье представлена информация о работе с методом Hong Kong Virtual Account: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | банковские платежи |
---|---|
Платёжные инструменты | банковские счета |
Регионы использования | HK |
Валюты платежей | HKD, CNY |
Конвертация валют | – |
Разовые оплаты | + |
Повторяемые оплаты | – |
Полные возвраты | – |
Частичные возвраты | – |
Выплаты | – |
Опротестования | – |
Особенности | при оплате пользователь может указывать сумму, отличную от суммы в запросе; информация о реагировании на такие случаи представлена далее |
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить в ecommshop |
Схема работы
В проведении отдельного платежа с использованием метода Hong Kong Virtual Account задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса провайдера.
Основные операции
Для проведения платежей и выполнения операций с использованием метода Hong Kong Virtual Account могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок). При этом, независимо от используемых интерфейсов, для этого метода характерны следующие ограничения.
При работе с методом Hong Kong Virtual Account, независимо от используемых интерфейсов, актуальны следующие ограничения.
Суммы, HKD | ||
---|---|---|
минимум | максимум | |
Оплаты | – | 4 000 000,00 |
Сценарии использования
Проведение оплат с использованием метода Hong Kong Virtual Account осуществляется с отображением платёжной инструкции пользователю.
Пользовательский сценарий оплаты через Payment Page (в базовом варианте с выбором пользователем метода и банка и перенаправлением с итоговой страницы платёжной формы к веб-сервису) выглядит следующим образом.
Общие сценарии проведения оплат можно представить следующим образом.
Обработка некорректных платёжных данных
При работе с этим методом вся необходимая для оплаты информация представляется пользователю в инструкции. Вместе с тем, поскольку пользователь совершает перевод через сервис своего банка, он может преднамеренно или случайно нарушить правила заполнения данных. В таком случае платёж признаётся проведённым и в итоговом оповещении о проведении этого платежа содержится информация о сумме, которая была указана пользователем при оплате, независимо от того, совпадает ли она с суммой в запросе, после чего разрешение этой ситуации осуществляется на стороне мерчанта.
Предположим, что для инициирования платежа был использован следующий запрос через Gate с указанием суммы 300,00 HKD:
Если пользователь указал при оплате сумму 250,00 HKD и платёж был успешно обработан на стороне провайдера и платёжной платформы, то от платформы к веб-сервису отправляется оповещение следующего вида с фактической суммой, указанной пользователем. При этом на стороне мерчанта необходимо иметь возможность обработать такое оповещение, несмотря на отличие фактической суммы платежа от исходной суммы в запросе.
Оплаты через Payment Page
Общая информация
Для проведения оплаты через Payment Page с использованием метода Hong Kong Virtual Account со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Hong Kong Virtual Account через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода Hong Kong Virtual Account необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
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 Virtual Account необходимо указывать код этого метода в параметре
force_payment_method
—hk-va
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода Hong Kong Virtual Account должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор пользователя и подпись.
Формат оповещений
Для оповещений о результатах оплат с применением метода Hong Kong Virtual Account используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 456
для пользователя customer1
была проведена оплата в размере 100,00 HKD
.
В следующем примере оповещение свидетельствует об отклонённой оплате.
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
- Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
Для проведения оплаты через Gate с использованием метода Hong Kong Virtual Account со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять промежуточное оповещение от платёжной платформы и отобразить платёжную инструкцию пользователю.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Hong Kong Virtual Account через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на оплаты с применением метода Hong Kong Virtual Account необходимо учитывать следующее:
- Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/banks/hk-va/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 Virtual Account должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, а также подпись.
Формат промежуточных оповещений для отображения платёжной инструкции
Для отображения пользователям платёжной инструкции при проведении каждого платежа с использованием метода Hong Kong Virtual Account необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в массив display_data
. Формат таких оповещений является типовым (подробнее), при этом в состав массива display_data
включаются следующие параметры:
type
— тип передаваемых данных (в значении всегда передаётсяadd_info
);title
— название передаваемых данных, которые необходимо отобразить пользователю (в значении всегда передаётсяvirtual_account_number
);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. |
Формат итоговых оповещений
Для оповещений о результатах оплат с применением метода Hong Kong Virtual Account используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 456
для пользователя customer1
была проведена оплата в размере 100,00 HKD
.
В следующем примере оповещение свидетельствует об отклонённой оплате.
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу Hong Kong Virtual Account, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.