Banks of Hong Kong
Обзор
Введение
Banks of Hong Kong — метод, позволяющий проводить платежи в гонконгских долларах и юанях с использованием банковских счетов в Гонконге. Для этого метода в платёжной платформе ecommpay поддерживаются выплаты.
В этой статье представлена информация о работе с методом Banks of Hong Kong: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | банковские платежи |
---|---|
Платёжные инструменты | банковские счета |
Регионы использования | HK |
Валюты платежей | HKD, CNY |
Конвертация валют | – |
Разовые оплаты | – |
Повторяемые оплаты | – |
Полные возвраты | – |
Частичные возвраты | – |
Выплаты | + |
Опротестования | – |
Особенности | – |
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить в ecommshop |
Схема работы
В проведении отдельного платежа с использованием метода Banks of Hong Kong задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса провайдера.
Основные операции
Для проведения платежей и выполнения операций с использованием метода Banks of Hong Kong могут применяться различные интерфейсы платёжной платформы. Так выплаты могут проводиться через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие ограничения.
При работе с методом Banks of Hong Kong, независимо от используемых интерфейсов, актуальны следующие ограничения.
Суммы, HKD | ||
---|---|---|
минимум | максимум | |
Выплаты | – | 4 000 000,00 |
Сценарии использования
Проведение выплат осуществляется с уведомлением пользователей через веб-сервис мерчанта.
Вместе с тем, к особенностям работы с методом Banks of Hong Kong можно отнести то, что для каждого платежа с использованием этого метода должен быть указан конкретный банк. При работе через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Способы работы с идентификаторами банков описаны в следующем подразделе, Поддержка со стороны банков.
Поддержка со стороны банков
В следующей таблице в ознакомительных целях приведены названия и идентификаторы некоторых банков, поддерживающих работу с методом Banks of Hong Kong. Более подробный список представлен по ссылке: Список поддерживаемых банков. Данную информацию следует уточнять у курирующего менеджера ecommpay.
Банк | ID |
---|---|
BANK OF CHINA (HONG KONG) LIMITED Cheung Chau Branch | 54661 |
BANK OF COMMUNICATIONS CO., LTD. Hong Kong Branch | 53911 |
CHANG HWA COMMERCIAL BANK LTD Hong Kong Branch | 53121 |
CHINA CITIC BANK INTERNATIONAL LIMITED Mei Foo Branch | 36991 |
CHINA CONSTRUCTION BANK (ASIA) CORPORATION LIMITED Hunghom Ma Tau Wai Road Branch | 53571 |
CHONG HING BANK LTD Hong Kong Main Branch | 31061 |
CHONG HING BANK LTD North Point Branch | 54311 |
CIMB BANK BERHAD Hong Kong Branch | 54021 |
CITIBANK (HONG KONG) LIMITED Mei Foo Sun Chuen Branch | 54481 |
DAH SING BANK LTD Fortress Hill Branch | 54071 |
DAH SING BANK LTD Tai Po Branch | 53181 |
DBS BANK (HONG KONG) LIMITED Yaumatei Branch | 54441 |
FUBON BANK (HONG KONG) LIMITED Chai Wan Branch | 53851 |
FUBON BANK (HONG KONG) LIMITED Yuen Long Branch | 48651 |
HANG SENG BANK LTD Fortune Kingswood Branch | 35031 |
HANG SENG BANK LTD Tai Po Branch | 54651 |
INDUSTRIAL AND COMMERCIAL BANK OF CHINA (ASIA) LTD Central Branch | 54471 |
NANYANG COMMERCIAL BANK LTD Western Branch | 54221 |
OCBC WING HANG BANK LIMITED Fortress Hill Branch | 53031 |
PUBLIC BANK (HONG KONG) LIMITED Prince Edward Branch | 53821 |
PUBLIC BANK (HONG KONG) LIMITED Tai Po Branch | 44931 |
SHANGHAI COMMERCIAL BANK LTD Mongkok Branch | 54511 |
SHANGHAI COMMERCIAL BANK LTD West Point Branch | 54551 |
STANDARD CHARTERED BANK (HONG KONG) LIMITED Kwun Tong Branch | 54011 |
TAI YAU BANK LTD Head Office | 25681 |
THE BANK OF EAST ASIA, LTD Chai Wan Branch | 43941 |
THE BANK OF EAST ASIA, LTD Main Branch | 27401 |
THE HONGKONG AND SHANGHAI BANKING CORPORATION LTD Paterson Street HPC | 54601 |
TMB BANK PUBLIC COMPANY LIMITED, HONG KONG Hong Kong Branch | 54061 |
WING LUNG BANK LTD Happy Valley Branch | 53991 |
С вопросами о работе с банками, поддерживающими метод Banks of Hong Kong, можно обращаться к курирующему менеджеру ecommpay.
Выплаты через Gate
Общая информация
Для проведения выплаты через Gate с использованием метода Banks of Hong Kong со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения выплаты выглядит следующим образом.
- Пользователь на стороне веб-сервиса инициирует выплату через Banks of Hong Kong.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение выплаты через Gate.
- Запрос на проведение выплаты поступает в платёжную платформу.
- В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе Формат ответа.
- В платёжной платформе обеспечиваются дальнейшая обработка запроса (с проверкой согласованности параметров) и его отправка в сервис провайдера.
- В сервисе провайдера выполняется обработка выплаты.
- От сервиса провайдера к платёжной платформе направляется информация о результате выплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате выплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате выплаты.
Информация о форматах запросов и оповещений, используемых для проведения выплат методом Banks of Hong Kong через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на выплаты с применением метода Banks of Hong Kong необходимо учитывать следующее:
- Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/banks/hk/payout
. Эта точка относится к группе /v2/payment/banks/{payment_method}/payout. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма выплаты в дробных единицах валюты;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемой выплаты;,
account
— сведения о счёте пользователя:bank_id
— идентификатор банка,number
— номер счёта,customer_name
— имя получателя.
- Валютой платежа может быть только HKD или CNY.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на выплату с применением метода Banks of Hong Kong должен содержать идентификатор проекта, базовые сведения о платеже (его идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, данные счёта и подпись.
{ "general": { "project_id": 383000, "payment_id": "12278b5d662764c9506b4db9df8c5c35", "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9Mtb3Lv...5vOA7w==" }, "customer": { "id": "fr-2374245", "ip_address": "192.0.2.0" }, "payment": { "amount": 10000, "currency": "HKD" }, "account": { "bank_id": 22791, "number": "1234567890", "customer_name": "John Doe" } }
{ "general": { "project_id": 383000, "payment_id": "12278b5d662764c9506b4db9df8c5c35", "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9Mtb3Lv...5vOA7w==" }, "customer": { "id": "fr-2374245", "ip_address": "192.0.2.0" }, "payment": { "amount": 10000, "currency": "HKD" }, "account": { "bank_id": 22791, "number": "1234567890", "customer_name": "John Doe" } }
Формат оповещений
Для оповещений о результатах выплат с применением метода Banks of Hong Kong используется типовой формат, описание которого представлено в разделе Работа с оповещениями.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 789
для пользователя customer3
была проведена выплата в размере 100,00 HKD
.
{ "project_id": 789, "payment": { "id": "ABC1234321", "type": "payout", "status": "success", "date": "2021-04-26T08:41:59+0000", "method": "hk", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "account": { "number": "1234567" }, "customer": { "id": "customer3" }, "operation": { "id": 4348000010681, "type": "payout", "status": "success", "date": "2021-04-26T08:41:59+0000", "created_date": "2021-04-26T08:41:54+0000", "request_id": "3d7ef0727decad0829d608cabd0f8a6d96fbd3a...006256", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "0", "message": "Success", "provider": { "id": 5181, "payment_id": "aff0b...cf9f2cd", "auth_code": "", "date": "2021-04-26T08:41:55+0000" } }, "signature": "1L2fmnHY/51dZPI1j/IVa9LqzEPR67j9pPghn...c545R1xsGzw0zQ==" } }
В следующем примере оповещение свидетельствует об отклонённой выплате.
{ "project_id": 0123, "payment": { "id": "ABC1234567", "type": "payout", "status": "decline", "date": "2021-04-26T08:41:59+0000", "method": "hk", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "account": { "number": "123456789" }, "customer": { "id": "customer1234" }, "operation": { "id": 4348000010681, "type": "payout", "status": "decline", "date": "2021-04-26T08:41:59+0000", "created_date": "2021-04-26T08:41:54+0000", "request_id": "a19b65b2463fa7377f518d49674275cbaa4397a7...004349", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "20000", "message": "General decline", "provider": { "id": 5181, "payment_id": "aff0b...cf9f2cd", "auth_code": "", "date": "2021-04-26T08:41:55+0000" } }, "signature": "eQxj9hXHVWFBDMcko2Tj0071CvnFPsp...A9CchCgVr/Hqbu6w==" } }
Дополнительные материалы
Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Выплаты — о том, как проводить выплаты через Gate.
- Работа с информацией об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Выплаты через Dashboard
При использовании интерфейса Dashboard можно проводить одиночные и массовые выплаты методом Banks of Hong Kong с единичной и пакетной отправкой запросов, называемые соответственно одиночными и массовыми.
- Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры (включая метод), отправить запрос и убедиться в проведении выплаты.
-
Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат.
При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе Сведения о массовых платежах, а параметры выплат — должны соответствовать требованиям, представленным в разделе Выплаты через Gate этой статьи (за исключением пункта о подписи).
Более подробная информация о проведении выплат через Dashboard представлена в отдельной статье.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу Banks of Hong Kong, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.