Skip to content

Latest commit

 

History

History
276 lines (219 loc) · 12 KB

README.md

File metadata and controls

276 lines (219 loc) · 12 KB
Raw

Intro

Banks in Hong Kong have provided API to access their data. They follow the timeline listed in HKMA and publish relevant API.

⚠️ WARNING ⚠️

All methods in this section are tested in sandbox environment only. Some critical error exists and may ruin the function (eg. typo of field names, actual data type not match the documentation).

Since only sandbox test data can be accessed, all development in this section will not try to fix any error. Thus you should expect a smooth development under sandbox environment but some BUGS in production.

Please kindly create issues to report bugs.

⚠️ Notice ⚠️

Some banks already published API for public to apply their services. After digging with their API, I gave up developing those API as it is way too complicated for me to handle those request.

Supported Banks

The API of different banks under a group (except Others) is very similar to each other (not 100% same). Codes should be able tp reuse in most cases.

HSBC Group

Name (EN) Name (TC) Code Developer Portal
The Hongkong and Shanghai Banking Corporation Limited 香港上海滙豐銀行有限公司 hsbc LINK
Hang Seng Bank Limited 恒生銀行有限公司 hs LINK

BOCHK

Name (EN) Name (TC) Code Developer Portal
Bank of China（Hong Kong）Limited 中國銀行(香港)有限公司 boc LINK
Chiyu Banking Corporation Limited 集友銀行有限公司 chiyu LINK
Nanyang Commercial Bank, Limited 南洋商業銀行有限公司 ncb LINK

JETCO Related

⚠️ All banks listed below use the same API provider. ⚠️

Developer Portal LINK

Name (EN) Name (TC) Code
Bank of Communications (Hong Kong) Limited 交通銀行（香港）有限公司 bch
The Bank of East Asia Limited 東亞銀行有限公司 bea
China Construction Bank (Asia) Corporation Limited 中國建設銀行（亞洲）股份有限公司 cal
China CITIC Bank International Limited 中信銀行（國際）有限公司 cbi
Chong Hing Bank Limited 創興銀行有限公司 chb
Citibank (Hong Kong) Limited 花旗銀行（香港）有限公司 ctn
Dah Sing Banking Group Limited 大新銀行集團有限公司 dsb
Fubon Bank (Hong Kong) Limited 富邦銀行（香港）有限公司 fbb
Industrial and Commercial Bank of China（Asia）Limited 中國工商銀行（亞洲）有限公司 icb
Public Bank (Hong Kong) Limited 大眾銀行（香港）有限公司 pbl
Shanghai Commercial Bank Limited 上海商業銀行有限公司 scb
OCBC Wing Hang Bank Limited 華僑永亨銀行有限公司 whb
CMB Wing Lung Bank Limited 招商永隆銀行有限公司 wlb
Airstar Bank Limited 天星銀行有限公司 vab1

Others

Name (EN) Name (TC) Code Developer Portal
DBS Bank (Hong Kong) Limited 星展銀行（香港）有限公司 dbs LINK
Standard Chartered Bank (Hong Kong) Limited 渣打銀行（香港）有限公司 sc LINK
Livi Bank Limited 理慧銀行有限公司 livi1 LINK
Fusion Bank Limited 富融銀行有限公司 fusion1 LINK
Ant Bank (Hong Kong) Limited 螞蟻銀行(香港)有限公司 ant12 LINK
Ping An OneConnect Bank (Hong Kong) Limited 平安壹賬通銀行(香港)有限公司 paob13 LINK
WeLab Bank Limited 匯立銀行有限公司 welab1 LINK
ZA Bank Limited 眾安銀行有限公司 za14 LINK

Usage

First, include the relevant module.

// require HSBC only
const hsbc = require("hkopendata").bank.hsbc;

// or require multiple module
const { hsbc, hs } = require("hkopendata").bank;

Next, initiate with credentials and do the searching. All the methods return a promise. You should handle the result or error properly.

hsbc.connect([params])
    .then(() => {
        // Initiate Success
        return hsbc.search([params])
    })
    .then(result => {
        // Process the result
    })
    .catch(error => {
        // Initiate error / Search error
    })

Environment

Before v1.7.0, this package always use sandbox setup. You need to update the package and follow the setup below to enable production environment.

By default, if the API provides a sandbox environment, this package would try to access it.

You need to use the correct credential and configuration for authorizing the API.

Use the following code to set current environment to Production:

// The following line should be invoked for production only
// and MUST BE placed before `bank.connect` or `bank.init`
bank.setProduction(true);

Even though some API won't seperate the production and sandbox environment, it is RECOMMENDED to include the above code for later compatibility.

Initiation

WARNING: The initiation method below is deprecated since v1.4.0. Check this for latest method.

Most of the banks requires these fields.

Name Description Accepted Remarks
id Client ID string May refer to developer or app credential
secret Client Secret string May refer to developer or app credential
lang Language of result en|tc|sc Not every bank requires, some may need to specify in search request. Not all languages are supported. 
// Applicable to most banks.
bank.init(id, secret, lang)

⚠️ DBS Initiation ⚠️

DBS uses a different way to authorize. You need to use the credentials in My Apps and generate your own JWT.

/**
 * @params {string} id          Partner Client Id
 * @params {string} secrect     Partner Client Secret
 * @params {string} user        App Username
 * @params {string} jwt         Your JWT
 */

// use `dbs.connect`
dbs.connect({ id, secret, user, jwt }, lang)
// or `dbs.init` for v1.3 or before
dbs.init(id, secret, user, jwt, lang)

If you are TESTING ONLY and don't want to worry about the x509 certificate or JWT token, follow these steps to authorize correctly:

  1. Go to Documentation page and try one of the API.
  2. In the API Playground page, select the Demo App
  3. Get the id(Client ID), secret(Client Secret), app(App Username) and jwt(App JWT token).
  4. Start initiation.

The token will be valid for 1 day. You will need to repeat the above steps for a new token.

⚠️ PAOB Initiation ⚠️

PAOB uses a different way to authorize. You need to sign each request using your private key. Visit the Official Guide and go to section 4. SDK usage guide for how to generate the key and use it to sign the request.

/**
 * @params                   {string}   id      App ID
 * @params {(data: string) => string}   sign    Your signing function
 */
// use `pabo.connect`
pabo.connect({ id, sign }, lang)

Initiation v1.4.0+

From v1.4.0, use bank.connect() instead of bank.init().

// For most banks
let credential = {
    id: YOUR_ID,
    secret: YOUR_SECRET
}

// For DBS
let credential = {
    id: YOUR_ID,
    secret: YOUR_SECRET,
    app: YOUR_USERNAME,
    jwt: YOUR_JWT,
}

// For LIVI
let credential = {
    secret: YOUR_SECRET,
}

// For PAOB
let credential = {
    id: YOUR_ID,
    sign: (DATA_TO_SIGN) => {
        // your function to sign the data
        return SIGNED_STRING;
    }
}

bank.connect(credential, lang)

Search

All banks use the same way to search for data.

// Remember it returns a promise
bank.search(searchType[, params])

If API accept extra parameters or headers, put those data to params.

bank.search(searchType, {
    headers: {
        fakeHeader: "value"
    },
    data: {
        fakeData: "value"
    }
})

Search Types

Different banks support different search type. Here list the general types:

Type Description
branch Branch information
atm ATM information
depositBox Safe deposit box information
saving|current|timeDeposit|foreignCurrency Different types of account
mortgage Mortgage information
creditCard Credit card information. Some may accept commercialCard
fx Foreign currency exchange information. Some may accept fx-{subType}
insurance Insurance information. Some may accept insurance-{subType}
investment|security Investment/Securities information. Some may accept {type}-{subType}
loan Loan information. Some may accept (un)securedLoan and (un)securedLend. Some may accept loan-{subType}.

For general information, you can check supported type of HSBC Group, BOCHK and JETCO below.

For the actual search type and sub type, always refer to the official documentation instead of this page. Create issues if a type should be supported but error Invalid search type occurs.

HSBC Group Search

Banks under HSBC Group does not support investment, insurance and security searching.

loan is replaced with securedLoan, securedLend, unsecuredLoan and unsecuredLend.

BOCHK Search

Banks under BOCHK does not support atm searching.

investment, security, insurance, loan and fx are replaced with {type}-{subType}. Check the endpoint URL (Format: /{type}/product/{subType}/v1) in official documetation to get the accepted sub types.

JETCO Search

Banks under JETCO does not support security searching.

loan is replaced with securedLoan, and unsecuredLoan. investment and insurance are replaced with {type}-{subType}. Check the endpoint URL (Format: /{type}/v1/{subType}) in official documetation to get the accepted sub types.

Result

Data retrieved will change the field names so that the specific field name among different banks means the same thing. Then, it would try to unify the format and structure to make the final result as similar as possible among all banks.

⚠️ Warning ⚠️

Same field name may refer to different thing among different banks due to:

  1. Insufficient detail in documentation to identify what the field is
  2. Mix up with very similar terms (in my point of view)

To check if the field actually refer to what you expected, try running utils.ToLocale() in both en and tc language.

bank.search(type)
    .then(result => {
        utils.ToLocale(result, lang, "bank")
    })
    .catch(() => {})

Useful Links

HKMA - Stage of 4 Open API Phases HKSTP - Data Studio of Open API for all banks

Footnotes

  1. Available since v1.7.0 ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7

  2. Feature currently disabled as I can neither create a developer account nor retrieve the base url of the API. No response for requesting an invitation code since March 2022. Contact me if you can access the developer portal. ↩

  3. This API require to sign the request but I'm not eligible to apply for sandbox testing. Function may not work as expected. ↩

  4. Feature currently disabled as I can neither create a developer account nor figure out the authentication way of the API. Contact me if you can access the developer portal. ↩