Hong Kong Virtual Account

Overview

Introduction

Hong Kong Virtual Account is a payment method which allows you to process payments in Hong Kong and Chinese yuan by using bank accounts in Hong Kong. The customer makes purchases by transferring funds to a virtual bank account via a mobile banking application. This method supports purchases.

This article provides information about working with the Hong Kong Virtual Account 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

Payment method type bank payments
Payment instruments bank accounts
Countries and regions HK
Payment currencies HKD, CNY
Currency conversion –
One-time purchases +
Credential-on-file purchases –
Full refunds –
Partial refunds –
Payouts –
Chargebacks –
Special considerations when making a purchase the customer can specify an amount different from the one specified in the request, information on how to handle such cases is provided below.
Obtaining access to the payment method and access fee refer to your ecommpay key account manager; additional information is available in ecommshop

Interaction diagram

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



Operations support

Various platform interfaces can be used to process payments and perform operations using the Hong Kong Virtual Account method. Purchases can be processed by using Payment Page, Gate and Dashboard (using payment links). At the same time, regardless of the interfaces used, the following limitations are applicable.

When working with the Hong Kong Virtual Account the following limitations are applicable.

  Amounts, HKD
minimum maximum
Purchases – 4,000,000.00

Processing scenarios

To perform a purchase by using the Hong Kong Virtual Account method, payment instructions need to be displayed to the customer.

The customer payment scenario via Payment Page (in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service) looks like this.

Figure: Proceeding to payment



Figure: Selecting method



Figure: Receiving instructions



Figure: Paying according to instructions



Figure: Redirecting to the payment form



Figure: Redirecting to the web service



General scenarios of processing purchases can be presented as follows.

Figure: Purchase by using Payment Page



Figure: Purchase by using Gate



Processing of incorrect payment information

When working with this method, all the necessary information for successful payment is provided to customers in the instructions. However, since the customers makes a transfer through the service of their Bank, they may intentionally or accidentally violate the rules of filling in data. The payment is admitted as completed, and the final callback of this payment contains information about the amount that was specified by the customer when making the payment, regardless of whether it matches the amount in the request. After that, the resolution of this situation is carried out on the merchant's side.

Let's say the 300.00 HKD amount was specified in the following request to initiate a payment by using Gate:

Figure: Example of data in the request

{
    "general": {
      "project_id": 1234567,
      "payment_id": "abc12345",
      "signature": "123abc...pkdme12"
    },
    "customer": {
      "id": "123"
      "ip_address": "192.0.2.0"
    },
    "payment": {
      "amount": 30000,
      "currency": "HKD"
  }
}

If the customer specified the 250.00 HKD amount when paying, and the payment was successfully processed on the platform and provider sides, the platform sends the callback of the following form to the web service (this callback contains information about the actual amount specified by the customer). With this in mind the callback needs to be processed on the merchant side despite the difference between the actual amount and the initial amount specified in the request.

Figure: Example of data in the callback

{
        "project_id": 3514,
        "payment": {
            "id": "EP0c8a-960e",
            "type": "purchase",
            "status": "success",
            "date": "2021-02-10T10:10:14+0000",
            "method": "hk-va",
            "sum": {
                "amount": 25000,
                "currency": "HKD"
            },
            "description": ""
        },
        "operation": {
            "id": 360,
            "type": "sale",
            "status": "success",
            "date": "2021-02-10T10:10:14+0000",
            "created_date": "2021-02-10T10:09:34+0000",
            "request_id": "cca222750e99b05bc6656ec2d82df16cbb241a7-00000001",
            "sum_initial": {
                "amount": 25000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 25000,
                "currency": "HKD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 5171,
                "payment_id": "161295179796",
                "auth_code": "",
                "date": "2021-02-10T10:09:57+0000"
            }
        },
        "signature": "9sHwkk4fbhwQg3PH/8ShWtbqgBZEcfaC+HnVrQe6DFFCQX14w=="
    }

Purchases by using Payment Page

General information

To process a purchase through Payment Page by using the Hong Kong Virtual Account method, the merchant's web service is required to 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 purchase processing are provided below.



Figure: Purchase processing by using Payment Page: step-by-step description

  1. A customer initiates a purchase in the web service.
  2. The web service sends the request for opening Payment Page to the specified ecommpay URL.
  3. The request for opening Payment Page is sent to the payment platform.
  4. The payment platform receives the request and validates the required parameters and signature.
  5. Payment Page is generated based on the project and request parameters.
  6. Payment Page is displayed to the customer.
  7. The customer selects the Hong Kong Virtual Account method.
  8. The request for processing the payment by using the Hong Kong Virtual Account method is received by the payment platform.
  9. The payment platform processes the request.
  10. The data for displaying the payment instructions is sent from the payment platform to Payment Page.
  11. The payment instructions are displayed to the customer.
  12. The customer completes all required payment steps.
  13. The purchase is processed in the provider service.
  14. The provider service sends a notification about the result to the payment platform.
  15. The payment platform sends the payment result callback to the web service.
  16. The payment platform sends the result information to Payment Page.
  17. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Hong Kong Virtual Account method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending purchase requests by using the Hong Kong Virtual Account method:

  1. The following parameters required for any payment must be specified:
    • project_id—project identifier obtained from ecommpay during integration
    • payment_id—payment identifier unique within the project
    • payment_currency—payment currency code in the ISO-4217 alpha-3 format
    • payment_amount—payment amount in the smallest currency unit
    • customer_id—customer identifier unique within the project
  2. The following parameters required for any payment must be specified: project_id, payment_id, payment_currency, payment_amount, customer_id.
  3. The currency of payment can only be HKD or CNY.
  4. If you need to have the payment form displayed with the Hong Kong Virtual Account method selected, set the force_payment_method parameter to hk-va.
  5. Additionally, any other parameters available for working with Payment Page can be used (details).
  6. After all target parameters are specified, generate a signature (details).

Thus, a correct request for opening the payment form using the Hong Kong Virtual Account method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer identifier and signature.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "HKD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Figure: Example of sufficient data in a purchase request

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "HKD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Callback format

The Hong Kong Virtual Account method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with information about a 100.00 HKD purchase made by the customer1 customer in the 456 project.

Figure: Example of callback data indicating that the purchase has been processed

{
        "project_id": 123,
        "payment": {
            "id": "12345678",
            "type": "purchase",
            "status": "success",
            "date": "2021-04-26T08:40:29+0000",
            "method": "hk-va",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 6301000010721,
            "type": "sale",
            "status": "success",
            "date": "2021-04-26T08:40:29+0000",
            "created_date": "2021-04-26T08:39:53+0000",
            "request_id": "faac1f505a3e188fb384d7eabc735335b32af288...006302",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 5171,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "tqmkAb32XGHYglWq3Nm7XD7Yq21fV21dcGBMPb7/ddzuts...qoumh8dQw=="
    }
}

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

Figure: Example of callback data indicating that the purchase has been declined

{
        "project_id": 0123,
        "payment": {
            "id": "123456789",
            "type": "purchase",
            "status": "decline",
            "date": "2021-04-26T08:40:29+0000",
            "method": "hk-va",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1234"
        },
        "operation": {
            "id": 5205000010711,
            "type": "sale",
            "status": "decline",
            "date": "2021-04-26T08:40:29+0000",
            "created_date": "2021-04-26T08:39:53+0000",
            "request_id": "9b430e9f97d5fa903985e482242f6638...0005206",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 5171,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "+a9OY3rEEhMlPpR54LJoQa...2HfVTKJO5LeUmFUDtfA=="
    }
}

Useful links

The following articles can be useful when implementing purchases via Payment Page:

Purchases by using Gate

General information

To process a purchase through Gate by using the Hong Kong Virtual Account method, the merchant's web service is required to do the following:

  1. Send a request with all the required parameters and signature to the ecommpay URL.
  2. Receive an intermediate callback from the payment platform and display the payment instructions to the customer.
  3. Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.



Figure: Purchase processing by using Gate: step-by-step description

  1. A customer initiates a purchase by using the Hong Kong Virtual Account method in the web service.
  2. The web service sends the request for processing the purchase 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).
  6. The payment platform performs further processing of the request (with parameter consistency check).
  7. The data for displaying the payment instructions is sent from the payment platform to the web service.
  8. The payment instructions are displayed to the customer.
  9. The customer completes all required payment steps.
  10. The purchase is processed in the provider service.
  11. The provider service sends the payment result notification to the payment platform.
  12. The payment platform sends the payment result callback to the web service.
  13. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Hong Kong Virtual Account method via Gate is presented further in this section. General information about working with the Gate API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending purchase requests by using the Hong Kong Virtual Account method:

  1. To initiate each purchase, send a separate POST request to the /v2/payment/banks/hk-qr/sale endpoint. This endpoint belongs to the group /v2/payment/banks/{payment_method}/sale.
  2. Each request must include the following objects and parameters:
    • Object general—general purchase information:
      • project_id—project identifier obtained from ecommpay during integration
      • payment_id—payment identifier unique within the project
      • signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification) (details)
    • Object payment—payment information:
      • amount—payment amount in the smallest currency unit
      • currency—payment currency code in the ISO-4217 alpha-3 format
    • Object customer—customer information:
      • id—customer identifier unique within the project
      • ip_address—customer IP address relevant for the initiated payment
  3. The currency of payment can only be HKD or CNY.
  4. Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Hong Kong Virtual Account method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer identifier and IP address and signature.

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "HKD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  }
}

Figure: Example of sufficient data in a purchase request

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "HKD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  }
}

Formats of intermediate callbacks for displaying payment instructions

Each payment made with the Hong Kong Virtual Account method requires displaying payment instructions to customers. To display payment instructions it is necessary to receive an intermediate callback from the payment platform and use the information included in the display_data array. The format of such callbacks is standard (details), and the following objects and parameters are included in the display_data array:

  • type—object type (the value is always add_info)
  • title—title of the parameter which needs to be displayed to the customer (the value is always virtual_account_number)
  • data—number of the generated virtual account

Figure: display_data example

"display_data": [
            {
                "type": "add_info",
                "title": "virtual_account_number",
                "data": "1213323442...523521424"
            }
]

Along with the payment instructions, it is recommended to display to the customer the information about the expiration date for performing the required steps. If the customer does not confirm the payment prior to expiration of the specified time, an error message is displayed.

The payment instructions to be displayed to the customer are provided below.

Payment instructions in Traditional Chinese Payment instructions in English
付款詳情 Payment Details
銀行名稱: DBS Bank (Hong Kong) Limited Bank Name: DBS Bank (Hong Kong) Limited
帳戶持有人姓名：DOLLARSMART GLOBAL PTE. LTD. LTD. Account Holder name: DOLLARSMART GLOBAL PTE. LTD.
銀行帳號：{{va_number}} Bank Account number: {{va_number}}
轉帳金額: {{amount}} Transfer amount: {{amount}}
貨幣：HKD Currency: HKD
失效日期 Expiration date
如何支付 How to pay
1) 打開您的銀行應用程序，並從您的帳戶開始新的轉帳。 1) Open your banking app and start a new transfer from your account.
2) 選擇“DBS BANK（HONG KONG）LIMITED”作為收款銀行。 2) Select "DBS BANK (HONG KONG) LIMITED" as a payee bank.
3) 輸入帳戶持有人姓名：“DOLLARSMART GLOBAL PTE. LTD.” 3) Enter account holder’s name: "DOLLARSMART GLOBAL PTE. LTD."
4) 輸入銀行帳號。 4) Enter the bank account number.
5) 如有需要，請選擇HKD貨幣和付款日期。 5) Select HKD currency and payment date if necessary.
6) 輸入要支付的金額。 6) Enter the amount to be paid.
7）選擇“CONFIRM”以繼續轉帳。 7) Select "CONFIRM" to proceed with the transfer.
確認後，付款處理時間少於1分鐘。 Payment processing takes less than 1 minute after confirmation.

Final callback format

The Hong Kong Virtual Account method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with information about a 100.00 HKD purchase made by the customer1 customer in the 456 project.

Figure: Example of callback data indicating that the purchase has been processed

{
        "project_id": 456,
        "payment": {
            "id": "12345678",
            "type": "purchase",
            "status": "success",
            "date": "2021-04-26T08:40:29+0000",
            "method": "hk-va",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 6301000010721,
            "type": "sale",
            "status": "success",
            "date": "2021-04-26T08:40:29+0000",
            "created_date": "2021-04-26T08:39:53+0000",
            "request_id": "faac1f505a3e188fb384d7eabc735335b32af288...006302",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 5171,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "tqmkAb32XGHYglWq3Nm7XD7Yq21fV21dcGBMPb7/ddzuts...qoumh8dQw=="
    }
}

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

Figure: Example of callback data indicating that the purchase has been declined

{
        "project_id": 0123,
        "payment": {
            "id": "123456789",
            "type": "purchase",
            "status": "decline",
            "date": "2021-04-26T08:40:29+0000",
            "method": "hk-va",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1234"
        },
        "operation": {
            "id": 5205000010711,
            "type": "sale",
            "status": "decline",
            "date": "2021-04-26T08:40:29+0000",
            "created_date": "2021-04-26T08:39:53+0000",
            "request_id": "9b430e9f97d5fa903985e482242f6638...0005206",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 5171,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "+a9OY3rEEhMlPpR54LJoQa...2HfVTKJO5LeUmFUDtfA=="
    }
}

Useful links

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

Analysis of payment results

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

  • Dashboard interface toolkit with 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 available by using the Data API interface.

If you have any questions, refer to the documentation (Dashboard and Using Data API) and ecommpay technical support.