# Banks of Hong Kong {#pm_hk_banks} статья о работе с платёжным методом Banks of Hong Kong, который позволяет проводить платежи в гонконгских долларах и юанях с использованием банковских счетов в Гонконге и для которого в платформе Ecommpay поддерживаются выплаты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_hk_banks_overview} статья о работе с платёжным методом Banks of Hong Kong, который позволяет проводить платежи в гонконгских долларах и юанях с использованием банковских счетов в Гонконге и для которого в платформе Ecommpay поддерживаются выплаты ### Введение {#section_ql3_5fj_stb .section} Banks of Hong Kong — метод, позволяющий проводить платежи в гонконгских долларах и юанях с использованием банковских счетов в Гонконге. Для этого метода в платёжной платформе Ecommpay поддерживаются выплаты. В этой статье представлена информация о работе с методом Banks of Hong Kong: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[HK](references/ru/countries/HK.md)| |Валюты платежей|[HKD](references/ru/currencies/HKD.md), [CNY](references/ru/currencies/CNY.md)| |Конвертация валют|–| |Разовые оплаты|–| |Повторяемые оплаты|–| |Полные возвраты|–| |Частичные возвраты|–| |Выплаты|+| |Опротестования|–| |Особенности|–| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [ecommshop](https://ecommpay.com/shop/payment-methods/bank-payouts-hong-kong/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Banks of Hong Kong задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_hk_banks_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Banks of Hong Kong могут применяться различные интерфейсы платёжной платформы. Так выплаты могут проводиться через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие ограничения. ||Суммы, [HKD](references/ru/currencies/HKD.md)| |минимум|максимум| |--|---------------------------------------------| |-------|--------| |Выплаты|–|4 000 000,00| ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение выплат осуществляется с уведомлением пользователей через веб-сервис мерчанта. ![](images/pm/ru_hk_banks_interfaces_gate_payout.svg "Выплата через Gate") Вместе с тем, к особенностям работы с методом Banks of Hong Kong можно отнести то, что для каждого платежа с использованием этого метода должен быть указан конкретный банк. При работе через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Способы работы с идентификаторами банков описаны в следующем подразделе, [Поддержка со стороны банков](pm_hk_banks.md#section_rqp_zdl_ggb). ### Поддержка со стороны банков {#section_rqp_zdl_ggb .section} В следующей таблице в ознакомительных целях приведены названия и идентификаторы некоторых банков, поддерживающих работу с методом Banks of Hong Kong. Более подробный список представлен по ссылке: [Список поддерживаемых банков](files_for_downloads/Banks%20of%20Hong%20Kong/pm_hk_banks_list.pdf). Данную информацию следует уточнять у курирующего менеджера 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 {#ru_pm_hk_banks_gate_payout} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения выплаты через Gate с использованием метода Banks of Hong Kong со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения выплаты выглядит следующим образом. ![](images/pm/ru_hk_banks_uml_gate_payout.svg) 1. Пользователь на стороне веб-сервиса инициирует выплату через Banks of Hong Kong. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение выплаты через Gate. 3. Запрос на проведение выплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе [Формат ответа](ru_gate_interaction_organisation.md#). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка выплаты. 8. От сервиса провайдера к платёжной платформе направляется информация о результате выплаты. 9. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате выплаты. Информация о форматах запросов и оповещений, используемых для проведения выплат методом Banks of Hong Kong через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md#). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на выплаты с применением метода Banks of Hong Kong необходимо учитывать следующее: 1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/hk/payout`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма выплаты в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемой выплаты; - `account` — сведения о счёте пользователя: - `bank_id` — идентификатор банка, - `number` — номер счёта, - `customer_name` — имя получателя. 3. Валютой платежа может быть только [HKD](references/ru/currencies/HKD.md) или [CNY](references/ru/currencies/CNY.md). 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на выплату с применением метода Banks of Hong Kong должен содержать идентификатор проекта, базовые сведения о платеже \(его идентификатор, сумму и код валюты\), идентификатор и IP-адрес пользователя, данные счёта и подпись. ```language-json { "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" } } ``` ```language-json { "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" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах выплат с применением метода Banks of Hong Kong используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `789` для пользователя `customer3` была проведена выплата в размере `100,00 HKD`. ```language-json { "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==" } } ``` В следующем примере оповещение свидетельствует об отклонённой выплате. ```language-json { "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==" } } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с выплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md#)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md#)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Выплаты](ru_Gate_payout.md)— о том, как проводить выплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Выплаты через Dashboard {#ru_pm_dash_payout} При использовании интерфейса Dashboard можно проводить *одиночные* и *массовые*выплатыметодом Banks of Hong Kong с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры \(включая метод\), отправить запрос и убедиться в проведении выплаты. - Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат. При этомдолжен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md#), а параметры выплат— требованиям, представленным в разделе [Выплаты через Gate](pm_hk_banks.md#) этой статьи \(за исключением пункта о подписи\). Более подробная информация о проведении выплат через Dashboard представлена в [отдельной статье](ru_dbl_payments.md#). ## Анализ результатов проведения платежей {#ru_pm_hk_banks_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Banks of Hong Kong, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay.