Banks of Hong Kong

Обзор

Banks of Hong Kong — платёжный метод, позволяющий проводить выплаты на банковские счета в Гонконге. Выплаты осуществляются через через Gate или Dashboard.

Характеристика

Тип платёжного метода банковские платежи
Платёжные инструменты банковские счета
Регионы использования HK
Валюты платежей HKD, CNY
Конвертация валют
Оплаты
Выплаты +
Оплаты по сохранённым данным
Полные возвраты
Частичные возвраты
Опротестования
Особенности
Организация и стоимость подключения по согласованию с курирующим менеджером ecommpay

Схема работы

В проведении отдельного платежа с использованием Banks of Hong Kong задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства Banks of Hong Kong.



Основные операции

Интерфейсы Суммы, HKD Время*
Payment Page CMS Plug-ins Gate Dashboard минимум максимум базовое предельное
Выплаты + + 4 000 000,00
* Базовое и предельное время определяются следующим образом:
  • Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
  • Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус decline. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.

Сценарии использования

Проведение выплат с использованием метода Banks of Hong Kong выполняется с уведомлением пользователей через веб-сервис мерчанта.

Рис.: Выплата через Gate



Поддержка со стороны банков

Проведение платежей с применением метода Banks of Hong Kong осуществляется через банки, поддерживающие работу с этим методом. Банкам соответствуют свои идентификаторы, которые используются при инициировании выплат через Gate.

Прим.: Далее в таблице в ознакомительных целях представлена информация о некоторых из поддерживаемых банков. Более подробный список представлен по ссылке: Список поддерживаемых банков. Данную информацию следует уточнять у курирующего менеджера ecommpay.
Табл. 1. Неполный список поддерживаемых банков
Банк 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

Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.

Выплаты через Gate

Общая информация

Для выплаты через Gate с использованием метода Banks of Hong Kong со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате выплаты. Полная схема проведения выплаты представлена далее.



Рис.: Проведение выплаты через Gate

  1. Пользователь на стороне веб-сервиса инициирует выплату.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение выплаты через Gate.
  3. Запрос на проведение выплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
  6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис провайдера.
  7. На стороне провайдера выполняется обработка платежа.
  8. От сервиса провайдера к платёжной платформе направляется оповещение о результате.
  9. От платёжной платформы к веб-сервису направляется оповещение о результате.
  10. От веб-сервиса пользователю направляется результат выплаты.

Информация о формате запросов и параметрах инициации выплат методом Banks of Hong Kong через Gate, а также о формате оповещений о результатах выплат приведена далее, общая информация о работе с API см. в разделе Работа с API.

Формат запросов

При работе с запросами на выплаты с применением метода Banks of Hong Kong необходимо учитывать следующее:

  1. Должен использоваться запрос к конечной точке /v2/payment/banks/hk/payout, отправляемый методом POST. Этот запрос относится к группе запросов для проведения платежей в одном из поддерживаемых банков: /v2/payment/banks/{payment_method}/payout
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — основные сведения:
      • project_id — идентификатор проекта,
      • payment_id — идентификатор платежа,
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • customer — сведения о пользователе:
      • ip_address — используемый IP-адрес,
      • id — идентификатор пользователя, уникальный в рамках проекта;
    • account — сведения о счёте пользователя:
      • bank_id — идентификатор банка,
      • number — номер счёта,
      • customer_name — имя получателя;
    • payment — сведения о платеже:
      • amount — сумма платежа, указанная в дробных единицах валюты;
      • currency — код валюты платежа в формате ISO-4217 alpha-3.
  3. Валютой платежа может быть только HKD или CNY.
  4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на выплату с применением метода Banks of Hong Kong должен содержать идентификаторы проекта, пользователя, банка и платежа, номер счёта и имя получателя, IP-адрес пользователя, валюту и сумму платежа, а также подпись:

Рис.: Пример запроса на выплату

{
    "general": {
      "project_id": 383000,
      "payment_id": "12278b5d662764c9506b4db9df8c5c35",
      "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9Mtb3Lv...5vOA7w=="
    },
    "customer": {
      "id": "fr-2374245",
      "ip_address": "1.1.1.1"
    },
    "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 также могут быть полезны следующие материалы:

Выплаты через Dashboard

При использовании интерфейса Dashboard можно проводить одиночные и массовые выплаты методом Banks of Hong Kong с единичной и пакетной отправкой запросов, называемые соответственно одиночными и массовыми.

  • Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры (включая метод), отправить запрос и убедиться в проведении выплаты.
  • Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат.

    При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе Сведения о массовых платежах, а параметры выплат должны соответствовать требованиям, представленным в разделе Выплаты через Gate этой статьи (за исключением пункта о подписи).

Более подробная информация о проведении выплат через Dashboard представлена в отдельной статье.

Анализ результатов проведения платежей

Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода Banks of Hong Kong доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей в разделе Аналитика.

Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:

  • Dashboard позволяет выгружать данные в формате CSV с помощью инструментов в разделе Отчёты. При этом можно выполнять разовые и периодические выгрузки информации на локальный компьютер.
  • Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы к конечной точке /operations/get.

С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ecommpay.