# Banks of Hong Kong {#pm_hk_banks}

An article about the payment method which allows you to process payments in Hong Kong dollars and Chinese yuan by using bank accounts in Hong Kong and supports payouts.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_hk_banks_overview}

An article about the payment method which allows you to process payments in Hong Kong dollars and Chinese yuan by using bank accounts in Hong Kong and supports payouts.

### Introduction {#section_t5z_rlg_ytb .section}

Banks of Hong Kong is a payment method which allows you to process payments in Hong Kong dollars and Chinese yuan by using bank accounts in Hong Kong.This method supports payouts.

This article provides information about working with the Banks of Hong Kong method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[HK](references/en/countries/HK.md)|
|Payment currencies|[HKD](references/en/currencies/HKD.md), [CNY](references/en/currencies/CNY.md)|
|Currency conversion|–|
|One-time purchases|–|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|+|
|Chargebacks|–|
|Special considerations|–|
|Obtaining access to the payment method and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/bank-payouts-hong-kong/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Banks of Hong Kong method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/eng_hk_banks_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Banks of Hong Kong method. Payouts can be processed by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following limitations are applicable.

| |Amounts, [HKD](references/en/currencies/HKD.md)|
|minimum|maximum|
|--|-----------------------------------------------|
|-------|-------|
|Payouts|–|4,000,000.00|

### Processing scenarios {#section_fgt_sdl_ggb .section}

To process a payout, you need to notify the customer via the web service.

![](images/pm/eng_hk_banks_interfaces_gate_payout.svg "Payout by using Gate")

At the same time, the specifics of working with the method include the necessity of selecting a bank for each payment. When payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Ways of using bank identifiers are described in the next subsection, [Supported banks](pm_hk_banks.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

The following table lists the names and identifiers of some banks supported by the Banks of Hong Kong method, the list may change without additional notice. For more details, see the [List of the supported banks](files_for_downloads/Banks%20of%20Hong%20Kong/pm_hk_banks_list.pdf). For the most recent list of supported banks, contact your Ecommpay Key Account Manager.

|Bank|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|

If you have any questions about working with banks supported by the Banks of Hong Kong method, refer to your Ecommpay account manager.

## Payout by using Gate {#en_pm_hk_banks_gate_payout}

### General information {#section_lsx_3jl_ggb .section}

To process a payout through Gateby using the Banks of Hong Kong method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of payout processing are provided below.

![](images/pm/eng_hk_banks_uml_gate_payout.svg)

1.  A customer initiates a payout by using the Banks of Hong Kong method in the web service.
2.  The web service sends the request for processing the payout by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The payout is processed on the side of the provider service.
8.  The provider service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the payout result information from the web service.

Information about the formats of requests and callbacks used for processing payouts by using the Banks of Hong Kong method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending payout requests by using the Banks of Hong Kong method:

1.  To initiate each payout send a separate POST request to the `/v2/payment/banks/hk/payout` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general payout information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payout
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
        -   `number`—customer account number
        -   `customer_name`—customer name
3.  The currency of payment can only be [HKD](references/en/currencies/HKD.md) or [CNY](references/en/currencies/CNY.md).
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct payout request by using the Banks of Hong Kong method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, as well as account information and signature.

```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"
  }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The Banks of Hong Kong method uses the standard format for callbacks to deliver payout results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 HKD` payout made for the `customer3` customer in the `789` project.

```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=="
    }
}
```

The following is the example of a callback with information about a declined payout.

```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=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing payouts via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Payouts](en_Gate_payout.md)—about processing of payouts by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Dashboard {#en_pm_dash_payout}

When working with Dashboard, you can process *single* and *mass* payoutsby using the Banks of Hong Kong method.

-   To process a single payout, open the payout form, specify all required parameters \(including the payment method\), send a request and verify that the payout has been processed.
-   To process a mass payout, prepare and upload a file with information about all target payouts, send a batch request, and verify that the payouts have been processed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section.The payout parameters must comply with the [requirements](pm_hk_banks.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More information about processing payouts by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payment results {#en_pm_hk_banks_dash_analysis}

To analyse information about payments made with the Banks of Hong Kong method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.