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

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

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

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


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

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

В следующей таблице в ознакомительных целях приведены названия и идентификаторы некоторых банков, поддерживающих работу с методом Banks of Hong Kong. Более подробный список представлен по ссылке: Список поддерживаемых банков. Данную информацию следует уточнять у курирующего менеджера ecommpay.

Рис. 2. Список банков
Банк 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 и принять оповещение о результате. Полная схема проведения выплаты выглядит следующим образом.



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

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

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

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

  1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/hk/payout. Эта точка относится к группе /v2/payment/banks/{payment_method}/payout.
  2. В каждом запросе должны использоваться следующие объекты и параметры:
    • 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 — имя получателя.
  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": "192.0.2.0"
    },
    "payment": {
      "amount": 10000,
      "currency": "HKD"
  },
    "account": {
      "bank_id": 22791,
      "number": "1234567890",
      "customer_name": "John Doe"
  }
}
Рис. 4. Пример достаточного набора данных для запроса на выплату
{
    "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.

Рис. 5. Пример данных из оповещения о проведении выплаты
{
        "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=="
    }
}

В следующем примере оповещение свидетельствует об отклонённой выплате.

Рис. 6. Пример данных из оповещения об отклонении выплаты
{
        "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.