FINI API User Guide

Contents

Introduction

Connectivity Setup

2.1

Create Agent Profile

2.2

Create Machine Profile

2.3

Obtain FINI API JWT Access Token

2.4

Invoke FINI APIs

End-to-End Encryption

3.1

Obtaining Crypto Metadata for Encryption

3.2

Encrypting API Requests

3.3

Decrypting API Responses

3.4

End-to-End Encryption Error Codes and Messages

Formats and Conventions

4.1

Identifiers

4.2

Data Formats

4.3

Request Field Conventions

4.4

Response Field Conventions

API Endpoints

5.1

Overview

5.2

Throttles

IPO Reference Data

6.1

Enquire IPO List

6.2

Enquire IPO Reference Data

EIPO Subscription

7.1

Add EIPO Subscription Entries

7.2

Change EIPO Subscription Entries

7.3

Invalidate EIPO Subscription Entries

7.4

Enquire EIPO Subscription Entries

EIPO Funding

8.1

Enquire EIPO Funding

8.2

Confirm EIPO Funding

FAQs for External User Testing (EUT) & Production

9.1

FINI API Connectivity

9.2

FINI API Authentication

9.3

EIPO Subscription Entries APIs encryption

9.4

FINI API endpoint validation

9.5

Miscellaneous

Version(s)

Publication Date

Version

25 Jul 2023

Changes:

[Current]

 Update message sample on field priceMax and poMaxValue to correct syntax (Section 8.1.2)

6 June 2023

Changes:

 Update host name of production Access Management server (Section 2.3.3)

 Update description of field “specialistTechIndicator” (Enquire IPO Reference Data Endpoint)

 Update descriptions of fields “idNum” and “fullNameChi”, field “fulNameEng” supports

alphanumeric characters (Section 7.1.1 & 7.2.1 )

 Update FAQ in Section 9

21 April 2023

Changes:

 Add field “specialistTechIndicator” (Enquire IPO Reference Data Endpoint) - available in End

User Testing environment from 8 May 2023

 Revise field length and description of “nomBankAcctNum” (Enquire EIPO Funding Endpoint)

 Add FAQ in Section 9

21 February 2023

Changes:

 Revise the request example (recordID) of Enquire EIPO Subscription Entries (see Section

7.4.1)

 Revise the request example (transactionRef) of Enquire EIPO Funding (see Section 8.1.1)

20 January 2023

Changes:

 Revise field formats for “nomCur” (and the currency code list), “clawback” and “pricingDate”

(Enquire IPO Reference Data Endpoint)

 Rename field “frcoLevy” to “afrcTransactionLevy” (Enquire IPO Reference Data Endpoint)

 Revise field length and description of “partName” and add “Not Applicable” code to

“preFundingStatus” and “settlementStatus” (Enquire EIPO Funding Endpoint)

8 November 2022

Cosmetic updates:

 Added table of contents for other FINI User Guides

 Amended references to Agent and Machine Profile setup to HKEX Access Management User

Guide (from HKEX Client Connect User Manual) (See Section 2)

9 September 2022

Changes:

 Amended Java implementation sample source code for generating X-FINI-SIGNATURE header

(See Section 3.2.3)

 Added section to explain structure of unsuccessful responses (See Section 4.4.3)

 Removed upwards price flexibility-related fields (Enquire IPO Reference Data Endpoint and

Enquire EIPO Funding Endpoint)

13 July 2022

Changes:

 "sub" field for signing Agent Profile JWT (G1) has been amended from "hkexapi" to the user’s

Company ID in Client Connect (See Section 2.3.1.2)

27 May 2022

Changes:

 Supplemented End-to-End Encryption procedures (See Section 3)

 Added warrants fields for SPACs (Enquire IPO Reference Data Endpoint)

 Renamed several adviser fields for SFC Code of Conduct (Enquire IPO Reference Data

Endpoint)

Minor formatting:

 All data payloads unified as arrays (from objects)

 IPO identifier unified as "ipoID"

 IPO Status values updated for "Suspended" and "Cancelled"

5 January 2022

Initial version released to market participants in preparation of market testing.

2 Connectivity Setup



To access the FINI API Gateway, market participants are required to create an Agent profile and at most 2 Machine

profiles under their Company profile on the HKEX Access Management Platform.



After the Agent profile and Machine profile(s) have been created, FINI API users, as OAUTH client, have to pass

2 JSON Web Tokens (JWTs¹): Agent Profile JWT (G1) and Machine Profile JWT (G2), to the HKEX Access

Management (AM) server for authentication.



If authentication is successful, the AM server will return a FINI API JWT access token to API users. FINI API users

have to pass this FINI API access token in the calling FINI APIs. The integrity and validity of FINI API JWT access

token will be verified at the FINI API Gateway.



FINI API Gateway and HKEX Access Management (AM) server are assessed via Internet and TLS V1.2 will be

used for encryption.

2.1 Create Agent Profile



Each company can create at most one Agent profile for FINI API access.



To create an Agent Profile on the HKEX Access Management Platform, FINI API users have to generate JSON

Web Key (JWK²) with an expiry date. To enhance security, each agent key must be renewed every year. Therefore,

the expiry date must not be more than one year from registration time.



The following parameters are suggested for JWK generation:

Parameter

Value

Key Type

RSA

Key Size

2048

Key Use

Signature

Algorithm

RS256

Key ID

SHA-256 hash³ value of JWK

Expiry Date

Key expiration time, in Epoch time format

An example of JWK public key is shown below:

{

"keys": [

{

"kty": "RSA",

"e": "AQAB",

"use": "sig",

"kid":"eNL6Vj7vwaxjtwL+5QM=",

"alg": "RS256",

"n": "i4atD3PYe8YW7v8m

"exp": 1618307105

}

]

}



To facilitate key renewal, API users can register at most 2 public keys for each Agent profile so that API users can

renew and register a new public key before the existing key expires. Afterwards, API users can change their system

to rotate to the new JWK in generating the G1 JWT with their own plan before the existing key expires.

¹ Refer to RFC 7519 at https://tools.ietf.org/html/rfc7519.

² Refer to RFC 7517 at https://datatracker.ietf.org/doc/html/rfc7517.

³ Refer to RFC 7638 at https://datatracker.ietf.org/doc/html/rfc7638.



Please refer to the 5. API PROFILE MAINTENANCE (for FINI only) section of the HKEX Access Management

User Guide for detailed steps of agent profile maintenance.

2.2 Create Machine Profile



Each company can create at most 2 Machine profiles for FINI API access. As such, API users can set up 2

machines submitting API requests to FINI concurrently for their company.



To create a Machine Profile on the HKEX Access Management Portal, FINI API users have to generate JSON

Web Key (JWK) with an expiry date. To enhance security, each machine key must be renewed every year.

Therefore, the expiry date must not be more than one year from registration time.



The following parameters are suggested for JWK generation:

Parameter

Value

Key Type

RSA

Key Size

2048

Key Use

Signature

Algorithm

RS256

Key ID

SHA-256 hash value of JWK

Expiry Date

Key expiration time, in Epoch time format

An example of JWK public key is shown below:

{

"keys": [

{

"kty": "RSA",

"e": "AQAB",

"use": "sig",

"kid":"eNL6Vj7vwaxjtwL+5QM=",

"alg": "RS256",

"n": "i4atD3PYe8YW7v8m

"exp": 1618307105

}

]

}



To facilitate key renewal, API users can register at most 2 public keys for each Machine profile so that API users

can renew and register a new public key before the existing key expires. Afterwards, API users can change their

system to rotate to the new JWK in generating the G2 JWT with their own plan before the existing key expires.

2.2.1 Grant API Function to Machine Profile



Each machine profile must be granted the appropriate identities and API roles for invoking the corresponding FINI

API(s). The following FINI API Roles can be granted to a machine profile:

FINI Identity

FINI API Role

Available API Category

FINICP

 EU_finiIPORefDataAPI

 IPO Reference Data

 EU_finiPOSubAPI

 EIPO Subscriptions

FINDB

 EU_finiIPORefDataAPI

 IPO Reference Data

 EU_finiPOFundAPI

 EIPO Funding

Other FINI identities

 EU_finiIPORefDataAPI

 IPO Reference Data

 Please refer to the User Management section of the HKEX Access Management User Guide for detailed steps of

agent profile maintenance.

2.3 Obtain FINI API JWT Access Token



Before invoking FINI API, API users must call an API to obtain a FINI API JWT Access Token from the HKEX

Access Management (AM) server by passing the G1 and G2 JWT tokens. If authentication is successful, AM server

will return a FINI API JWT access token to API users.



API users have to generate the G1 and G2 JWT tokens according to their formats described as follows:

2.3.1 Prepare Agent Profile JWT (G1)

2.3.1.1 Header

Parameter

Type

Description

alg

RS256

RS256 should be used for algorithm to encrypt JWT.

typ

JWT

Sample Agent Profile JWT Header:

{

"alg": "RS256",

"typ": "JWT"

}

2.3.1.2 Payload

Parameter

Sample

Description

aud

https://<CCAM>/openam/oauth

Value of the <CCAM > may be different for production and test

2/eu/access_token

environments.

iss

Agent JWT Issuer value as registered in Agent Profile on the HKEX Access

Management Portal.

exp

1610440800

Specifies the expiration time. This is the Unix epoch time.

Must be less than 30 minutes from current system time

sub

CP123456

The user’s Company ID on the HKEX Access Management Portal.

Sample of Agent Profile JWT Payload:

{

"aud": "https://<fr am>/openam/oauth2/eu/access_token",

"iss": "https://www.finibroker.com/jwtissuer",

"exp": 1610440800,

"sub": "CP123456"

}

2.3.1.3 Sign Agent Profile JWT (G1)



Agent Profile JWT will be signed by private Agent JWK key. This value will be expected in “assertion” field in

Authentication request parameter.

2.3.2 Prepare Machine Profile JWT (G2)

2.3.2.1 Header

Parameter

Type

Description

alg

RS256

RS256 should be used for algorithm to encrypt JWT.

typ

JWT

Sample Machine Profile JWT Header:

{

"alg": "RS256",

"typ": "JWT"

}

2.3.2.2 Payload

Parameter

Sample

Description

aud

https://<CCAM>/openam/oauth

Value of the <CCAM > may be different for production and test

2/eu/access_token

environments.

iss

0fd68f99-e64d-4544-b4d6-

Machine Profile UUID. Machine Profile UUID is system generated ID of

bcc1d7c12c1e

Machine profile on the HKEX Access Management Portal.

exp

1610440800

Specifies the expiration time. This is the Unix epoch time.

Must be less than 30 minutes from current system time

sub

0fd68f99-e64d-4544-b4d6-

Machine Profile UUID. Machine Profile UUID is system generated ID of

bcc1d7c12c1e

Machine profile.

Sample of Machine Profile JWT:

{

"aud": "https://<fr am>/openam/oauth2/access_token",

"iss": "0fd68f99-e64d-4544-b4d6-bcc1d7c12c1e",

"exp": 1610440800,

"sub": "0fd68f99-e64d-4544-b4d6-bcc1d7c12c1e"

}

2.3.2.3 Sign Agent Profile JWT (G2)



Machine Profile JWT will be signed by private Machine JWK key. Public JWK will be imputed by user in CC IDP

while create Machine profile. This value will be expected in “client_assertion” field in request parameter.

2.3.3 Call FINI API JWT Access Token API



API users must call an API to obtain a FINI API JWT Access Token from the HKEX Access Management (AM)

server by passing the G1 (Agent profile) and G2 (Machine profile) JWT tokens being prepared as described above.

AM server will decrypt and verify the G1 JWT and G2 JWT by the using the registered Agent public key and

Machine public key respectively.



AM server will return a valid FINI API JWT access token after the G1 JWT and G2 JWT are verified.

Host Name

https://connect-am.hkex.com.hk:443

URI

/openam/oauth2/eu/access_token

Method

POST

Request Header

Parameter

Type

Required

Sample Value

Description

Content-Type

String

application/x-www-form-urlencoded

Request Parameter

Parameter

Type

Required

Sample Value

Description

grant_type

String

urn:ietf:params:oauth:grant-type:jwt-

This specifies the Agent Profile assertion grant

bearer

type.

assertion

String

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVC

This specifies the signed Agent Profile (G1)

J9.eyJhdWQiOiJodH..'

JWT.

client_assertion_type

String

urn:ietf:params:oauth:client-assertion-

This specifies the Machine Profile client

type:jwt-bearer

assertion type.

client_assertion

String

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVC

This specifies the signed Machine Profile (G2)

J9.eyJhdWQiOiJodHRwOi8vd3d3Lmdhb

JWT.

WEtdGVjaC5jb206OTA4MC9zc28vb2F1

dGgyL2FjY2Vzc190b2tlbiIsImlzcyI6InRlc

3Rv…

Response Body

Parameter

Type

Required

Sample Value

Description

access_token

String

BNwWkbMD690HKLXhh0MOaQ0o3Hc

This is a JWT Access Token. This access

token will be passed while calling FINI API.

scope

String

CP00001

Company Id will be return as scope value.

token_type

String

Bearer

This specify the Access Token type.

expires_in

Number

This specify expiration of JWT Access Token

in seconds.

HTTP Status Code

ForgeRock Reference link here

Error Messages

Error

Error Description

Action

invalid_grant

JWT assertion is expired or invalid

Agent JWT (G1) expired

invalid_client

JWT has expired

Machine Profile JWT(G2) expired

invalid_request

JWT expiration time is unreasonable

Agent/Machine Profile JWT time is over 30 minutes

invalid_grant

JWT assertion is not valid

Agent Profile JWT found invalid or not able to parse

server_error

Failed to parse json: Unexpected end-of-

Machine Profile JWT could not parse

input in field name\n at […]

invalid_client

Client authentication failed

client_assertion_type is not valid

unsupported_grant_type

Unknown Grant Type, urn:ietf:params&#x3a

grant_type value is not valid

;oauth:grant-type:jwt-bearer

Sample Success Response (HTTP Status Code 200)

{

"access_token":

"eyJ0eXAiOiJKV1QiLCJraWQiOiI0aUNLRkIwUlhJeHl0b3IxcjNUb0JkUmlldnM9IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJoa2V4YXBpIiwiY3RzIjoiT0FVVEgyX1NUQVRFT

EVTU19HUkFOVCIsImF1ZGl0VHJhY2tpbmdJZCI6IjhkZTQ0OTdlLTMxYWItNDY3Yi1hMzU1LTlkNzE0OWExOTdhYS0xMzE2ODgiLCJpc3MiOiJodHRwczovL2Nvbm

5lY3QtYW0udTFjcC5oa2V4LmNvbS5oazo0NDMvb3BlbmFtL29hdXRoMi9ldSIsInRva2VuTmFtZSI6ImFjY2Vzc190b2tlbiIsInRva2VuX3R5cGUiOiJCZWFyZXIiLCJhdX

RoR3JhbnRJZCI6IkY0a05tTGFGYUUtellxeVpuSEZaZWl6YkgtWSIsImF1ZCI6IjE1YjIzNjljLTkyMjItNDM1Mi05ZDIzLTdjODEyYWUwNzc2ZSIsIm5iZiI6MTY0OTgzMDI

3MywiZ3JhbnRfdHlwZSI6InVybjppZXRmOnBhcmFtczpvYXV0aDpncmFudC10eXBlOmp3dC1iZWFyZXIiLCJzY29wZSI6WyJDUDAwMzk4Il0sImF1dGhfdGltZSI6LTEs

InJlYWxtIjoiL2V1IiwiZXhwIjoxNjQ5ODMzODczLCJpYXQiOjE2NDk4MzAyNzMsImV4cGlyZXNfaW4iOjM2MDAsImp0aSI6InNzZDhmZHR6VW5sMWY3aVBhVzVSczF

NUFNzQSJ9.NHu1-0bPRMpw-e6YTZYiAcvhlrL6ZIj6NMjB84BYSdpEMX_Xxw9pPgu4IazzEsyO9G1kd4A0_EHWkiU6mW00A6LmrWhvgwRC3ve7Q_QORPa--

p0MoKMlC1FQ5D7uNDd6MnlOxR04rVDGYGAON3ElTNNbxZchkQj9WhSXZlNHsVJpJKSpWcZYyinYUsLkd-xBNaEiT8hbQCwX_NqqnI-

7GaQkNEl0XdmU5YQ0cBUe1DsLXwztrv7IiwKAPrfFMqWg0heAgkbgYuIuq_OVudwMqg9SDS_whzwKEZqSKw6DCndQZbo_jbAcCFS4vqlIcc5DjVfXcSqqZ-

D3yYs9AcFy8g",

"scope": "CP00001",

"token_type": "Bearer",

"expires_in": 30

}

Sample Error Response (HTTP Status Code 400)

Sample 1: When Agent JWT found expired (G1).

{

"error_description": "JWT assertion is expired or invalid",

"error": "invalid_grant"

}

Sample 2: When Machine Profile JWT found expired (G2).

{

"error_description": "JWT has expired",

"error": "invalid_client"

}

Sample 3: When Agent/Machine Profile JWT time found.

{

"error_description": "JWT expiration time is unreasonable.",

"error": "invalid_request"

}

Sample 4: When Agent Profile JWT found invalid/Not able to parse.

{

"error_description": "JWT assertion is not valid",

"error": "invalid_grant"

}

Sample 5: When Machine Profile JWT could not parse.

{

"error_description": "Failed to parse json: Unexpected end-of-input in field name\n at […]",

"error": "server_error"

}

Sample 6: When client_assertion_type is not valid

2.3.4 FINI API JWT Access Token



If authentication is successful, AM server will return a FINI API JWT access token to API users. Each FINI API

JWT access token has a validity of 30 seconds. Therefore, API users can reuse the same JWT access token to

invoke FINI API’s continuously until the access token expires. After the JWT access token expires, API users have

to obtain a new access token from AM server again.



The structure of the FINI API JWT access token is as follows:

2.3.4.1 Header

Name

Type

Sample Value

Description

typ

String

JWT

This specify the type of JWT.

kid

String

wU3ifIIaLOUAReRB/FG6eM1P1QM=

The kid of server’s public key signing the Access Token.

alg

String

RS256

This specifies the algorithm used for signing the Access Token.

Sample Access Token Header Example

{

"typ": "JWT",

"kid": "wU3ifIIaLOUAReRB/FG6eM1P1QM=",

"alg": "RS256"

}

2.3.4.2 Payload

Attributes defined in the FINI API JWT Access Token Payload:

Name

Type

Sample Value

Description

sub

String

CP123456

This specify “sub” field of agent JWT.

cts

String

OAUTH2_STATELESS_GRANT

This specify the core token service.

auditTrackingId

String

123e724e-68e1-45dd-bc9c-

This specify the Audit tracking id.

7757b048bc6e-3351

iss

String

https://connect-

This specify Agent issuer.Default value of “iss” will be like below.

am.hkex.com.hk:443/openam/oauth2/

http://<CCAM >/openam/oauth2/eu

tokenName

String

access_token

This specify the token name.

token_type

String

Bearer

This specify the return token type.

authGrantId

String

30nsq6cTJZwcJ-MGKYBwCSGSRcg

This specify the authentication grant id.

aud

String

<Machine-UUID>

This specify subject of Machine profile JWT.

nbf

Number

1618307105

The "nbf" (not before) claim identifies the time before which the

JWT MUST NOT be accepted for processing.

grant_type

String

urn:ietf:params:oauth:grant-type:jwt-

This specify the Agent profile grant type.

bearer

scope

String[]

["CP00001"]

This specify scope associated with respective Machine profile.

Company Id will be set as scope value.

auth_time

Number

-1

Time when the authentication has been performed.

realm

String

This specify the realm path.

exp

Number

1618310705

The "exp" (expiration time) claim identifies the expiration time on

or after which the JWT MUST NOT be accepted for processing.

iat

Number

1618307105

The "iat" (issued at) claim identifies the time at which the JWT

was issued.

expires_in

Number

This specify maximum time (Seconds) that the access token will

be valid for use within the application.

jti

String

QbmfS_qm04lTprLHUtS8mVxw1Po

This specify JWT id. Each Access Token has unique jti.

Sample Access Token (decoded) Example

{

"sub": "CP123456",

"cts": "OAUTH2_STATELESS_GRANT",

"auditTrackingId": "123e724e-68e1-45dd-bc9c-7757b048bc6e-3351",

"iss": "https://connect-am.hkex.com.hk:443/openam/oauth2",

"tokenName": "access_token",

"token_type": "Bearer",

"authGrantId": "30nsq6cTJZwcJ-MGKYBwCSGSRcg",

"aud": "0fd68f99-e64d-4544-b4d6-bcc1d7c12c1e",

"nbf": 1618307105,

"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",

"scope": [

"CP00001"

"auth_time": -1,

"realm": "/",

"exp": 1618310705,

"iat": 1618307105,

"expires_in": 30,

"jti": "QbmfS_qm04lTprLHUtS8mVxw1Po"

}

2.4 Invoke FINI APIs

2.4.1 HTTP Request



To invoke FINI APIs, API user must send a valid and active FINI API JWT access token in the “Authorization”

request header as bearer token.



API users must not modify the contents of the access token when passing it to invoke a FINI API.



Sample of FINI API JWT access token:

Bearer BNwWkbMD690HKLXhh0MOaQ0o3Hc



The HTTP Request Headers are required to be set as follows:

Name

Description

Sample Value

Method

HTTP Method of the API request

GET or POST

Content type

application/json

Authorization

FINI API JWT access token

Bearer

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NT

Y3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsI

mp0aSI6IjM5ZDg5MDc0LTI0NWQtNGQxNC04MzQ2LTI2MzQz

YjdlNTc2YyIsImlhdCI6MTYxNDA0OTg1MSwiZXhwIjoxNjE0MD

UzNDUxfQ.roqk6lSljCMDlQBBf4fd5CvTL1odneLj6LKSgHqXm8c



The production domain name of FINI API endpoints will be provided in a future iteration.

2.4.2 HTTP Status Code



FINI API Gateway will return one of the following HTTP status code after an API request is invoked:

Status Code

Status

Description

200

The request has succeeded

400

Bad Request

Invalid request

401

Unauthorized

The FINI API JWT access token is invalid

403

Forbidden

The client does not have access rights to the content

404

Not Found

The server cannot find the requested resource

429

Too Many Requests

Rate limiting

500

Internal Server Error

503

Service Unavailable

API Service is not available

504

Gateway Timeout

Timeout at the API Gateway

3 End-to-End Encryption

API endpoints with Personal Identifiable Information (PII) must adopt end-to-end encryption for both request and

responses on a data field level. The endpoints include:



Add EIPO Subscription Entries (see Section 7.1);



Change EIPO Subscription Entries (see Section 7.2);



Invalidate EIPO Subscription Entries (see Section 7.3); and



Enquire EIPO Subscription Entries (see Section 7.4).

Only the following PII data fields have to be encrypted in the API request and response, while other fields should not be

encrypted:

 ID Type of the applicant (idType)

 Issuing authority of the applicant’s identification document (idCountryJurisdiction)

 ID number of the applicant’s identification document.(idNum)

 Full English name of the applicant (fullNameEng)

 Full Chinese or non-English name of the applicant (fullNameChi)

3.1 Obtaining Crypto Metadata for Encryption

It is required to obtain Crypto Metadata, which includes FINI public key and Timestamp, for every API encryption request

by calling Crypto Metadata Request API. The system sequence diagram below illustrates the data flow for obtaining

crypto metadata for encrypting API data fields:

3.1.1 Request

GET

/api/crypto/meta

For invoking Crypto Metadata Request API, API user must obtain and send a valid and active FINI API JWT access

token as described in Section 2.3.

3.1.2 Response

Field

Type

Length

Description

Sample

code

String

0 to indicate ‘successful response’.

message

String

100

Empty string, i.e. "" to indicate successful

response.

data

Object

The crypto metadata including the public key

and timestamp

3.1

publicKey

String

1000

The X.509 RSA public key to be used in FINI,

MIIBIjANBgkqhkiG9w0BAQEF

encoded in base64 format

AAOCAQ8AMIIBCgKCAQEAu

h/iUUOPQEk/2HzBNcFMprLM

mp0Z/kUj69+eP2d03gkOFSh

Ofb/wI2Nmm3m7fwI/oFfab2qQ

gj4+I0F4zJzL9pd+QXSU+dme

EokXMVZpeqCr1zDn4I66usF

NC4NWQcP9XQpVxjmTzK6e1

LOpEk3wvRyW+mGqAJqPJv

matVmYXKvpmHdaOXN9vdK

15o6cYm5aEPg1+ih05+N+UI3

QeEYjv3O/b7wpvExBr52w0Z6

MELYeOEdWrvp7U3p8eJGaa

XTLkoqemIBWKfCefxqcn/tgW

4o/X6h0J38XhrQLULSGtPUB

Al3B4mfH504HI3cdX7pqnsgik

NnwWqfjew89z+gvFQIDAQAB

3.2

serverTimestamp

Integer

The FINI timestamp in Epoch milliseconds

1640070861735

format

{

"code": "0",

"message": "",

"data": {

"publicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuh/iUUOPQEk/2HzBNcFMprLMmp0Z/kUj69+eP2d03gkOFShOfb/w

I2Nmm3m7fwI/oFfab2qQgj4+I0F4zJzL9pd+QXSU+dmeEokXMVZpeqCr1zDn4I66usFNC4NWQcP9XQpVxjmTzK6e1LOpEk3wvRyW+mGqAJqPJvmatVmYXKvpmH

daOXN9vdK15o6cYm5aEPg1+ih05+N+UI3QeEYjv3O/b7wpvExBr52w0Z6MELYeOEdWrvp7U3p8eJGaaXTLkoqemIBWKfCefxqcn/tgW4o/X6h0J38XhrQLULSGtPUB

Al3B4mfH504HI3cdX7pqnsgikNnwWqfjew89z+gvFQIDAQAB",

"serverTimestamp": 1640070861735

}

Note: The publicKey and time difference (in millisecond format) between FINI server time and API machine system

time should be cached in the API machine’s memory. The time difference is calculated by subtracting the FINI

timestamp by API machine system time (in millisecond format).

3.2 Encrypting API Requests

The flowchart below illustrates the high-level workflow for encrypting API data fields:

A pseudorandom number generator that generates outputs from a non-deterministic source is strongly recommended

for the Data Key and Initialization Vector (IV) and encryption of the data payload.

Recommended library for Java:

Language

Library

Notes

Java

java.security.SecureRandom

In Java 8 or later, use SecureRandom.getInstanceStrong().

Meets RFC 4086’s Random Requirements for Security.

3.2.1 Generate Data Key and Initialization Vector (IV)

A 32-byte Data Key ("DataKeyBase64Str") and 12-byte IV ("IVBase64Str") must be generated on the client side to

encrypt the PII data fields in each API request and decrypt the PII data fields in the API response.

Field

Bytes

Description

Sample

DataKeyBase64Str

A Data Key that is cryptographically secure

IhJpZKbn9MnhWDz9UTPdNt6qllACKSWj4t1rN198QAg=

encoded in Base64 format.

IVBase64Str

An IV that is cryptographically secure encoded in

aSdkeptMB9NXdYJx

Base64 format.

Java implementation sample source code

int ivSize = 12;

byte[] iv = new byte[ivSize];

GCMParameterSpec ivKey;

SecretKey sKey;

// create a SecureRandom object for randomness

SecureRandom random = SecureRandom.getInstanceStrong();

// create Initialization Vector

random.nextBytes(iv);

ivKey = new GCMParameterSpec(128, iv);

String ivBas64Str = Base64.getEncoder().encodeToString(ivKey.getIV());

// create a KeyGenerator object with AES algorithm

KeyGenerator keyGen = KeyGenerator.getInstance("AES");

// generate Data Key

keyGen.init(256, random);

dataKey = keyGen.generateKey();

byte[] keyData = dataKey.getEncoded();

String dataKeyBase64Str = Base64.getEncoder().encodeToString(keyData);

3.2.2 Encrypting Data Fields

The data payload should be encrypted using the Data Key / IV, based on the following settings:

Configuration

Value

Algorithm

AES

Mode

GCM

Padding

NoPadding

The prefix "%enc_%" should then be appended to the final encrypted value to indicate the value is encrypted. Empty

string (“”) is still required to be encrypted with the same algorithm, On the other hand, "null" data value does not need

to be encrypted but will be included in generating the signed signature (X-FINI-SIGNATURE) header of the message.

Unencrypted sample request from the 7.1 Add EIPO Subscription Entries API endpoint (red text = to be encrypted):

{

"data": [{

"requestID": 1,

"ipoID": "1234",

"idList": [{

"idType": "1",

"idCountryJurisdiction": "HKG",

"idNum": "M011336(5)",

"fullNameEng": "Annabelle Wang",

"fullNameChi": "汪會夢"

}],

"appQuantity": "1000",

"firmID": "00000",

"ownRef": "f992b5c2-fd16-4e57-8387-738cb7aa75fb"

}

]

}

Encrypted sample request from the Section 7.1 Add EIPO Subscription Entries API endpoint (red text = encrypted

fields):

{

"data": [{

"requestID":"1",

"ipoID":"1234",

"idList":[{

"idType":"%enc_%eapFkonN3fzIDdSEkiD9EQg=",

"idCountryJurisdiction":"%enc_%ACzvoa5ZmoiXFScyhNbRKtxUgw==",

"idNum":"%enc_%BVeZ9hPEphW7EeSiE2UMP6bnM/QbklYusbM=",

"fullNameEng":"%enc_%CQnGpkKS/FHrGOMgkJROsmXZe+kEXEZ61hEcNn/P",

"fullNameChi":"%enc_%rtYCIbx0dZksk9K1QLpNT3zAjRi2YaZuWQ=="

}],

"appQuantity":"1000",

"firmID":"00000",

"ownRef":"f992b5c2-fd16-4e57-8387-738cb7aa75fb"

}

]

}

Java implementation sample source code

// Encrypt data field

byte[] clean = plainTextValue.getBytes();

SecretKeySpec secretKeySpec = new SecretKeySpec(dataKey.getEncoded(), "AES");

Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");

cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, ivKey);

byte[] encryptedByteArray = cipher.doFinal(clean);

String encryptedValueBase64 = "%enc_%" + Base64.getEncoder().encodeToString(encryptedByteArray);

3.2.3 Providing Encryption HTTP Request Headers

The encryption data key and signature of the API request must be prepared and sent to FINI with the following HTTP

headers and their values (red text = header value):

Header Key

Description

Sample

Authorization

FINI API JWT Access token obtained from

Bearer

the HKEX Access Management server

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM

(Section 2.3)

0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnR

ydWUsImp0aSI6IjM5ZDg5MDc0LTI0NWQtNGQxNC04MzQ

2LTI2MzQzYjdlNTc2YyIsImlhdCI6MTYxNDA0OTg1MSwiZX

hwIjoxNjE0MDUzNDUxfQ.roqk6lSljCMDlQBBf4fd5CvTL1od

neLj6LKSgHqXm8c

X-FINI-ENCRYPTED-KEY

Encrypted key as the concatenation of the

Step-by-step construction per below:

Data Key and IV (Section 3.2.1) with "#" as

the delimiter, encrypted under the following

Data Key

IhJpZKbn9MnhWDz9UTPdNt6ql

configurations:

lACKSWj4t1rN198QAg=

aSdkeptMB9NXdYJx

Configuration

Value

Concatenation of

IhJpZKbn9MnhWDz9UTPdNt6ql

Algorithm

RSA

Data Key and IV

lACKSWj4t1rN198QAg=#aSdke

Mode

None

(delimited by #)

ptMB9NXdYJx

Padding

PKCS1Padding

Header value (after

nQdkoc21+zKTy6Ri480Wk7UF

encryption)

hku3MH6/MyyzR5XnoQ9BD0M

BGySW2KCtZ0Nv25eA/jq6FFy

+jG45NR50R/zmRSPHGUcEU4

WDOmjdVEWnf0IV2+Vpnardk

d6ONGC94LxWm2wxyE2IKl3

WhnDY7EXvB9Oj3bWZAyHdd

9fE17d5kqnvGbXpA+R5qLS9d

2WDnRa3y+JcbvoZm5Y3qBVZ

Yv7h6G99dIipiFSrWs3KZlfzMe

eQp6VaP6Hg8jZeM5sfUlh6KC

348wgYfXjbfQ6iV3IwjKoeUJG

O2fy15zUwTLoqhlV5cCjFA1l6

Xvko0nnQcvl4vRiUfwVQuP2ll

kO/6PVnXg==

X-FINI-REQUEST-ID

Unique ID generated under the GUID v4

26219512b1da421eafc8560638ff69af

standard without any hyphens. FINI will

reject any duplicate Request ID in the same

day.

X-FINI-TIMESTAMP

Request timestamp calculated as the sum

Step-by-step construction per below:

between:

 Time difference in millisecond format

Time difference

between the local / server timestamps in

Local timestamp

1641264153167

the Crypto Metadata Response (Section

X-FINI-TIMESTAMP

1641264153182

3.1.2)

value

 Local timestamp in millisecond format

X-FINI-SIGNATURE

Signed signature in base64 format, as the

Step-by-step construction per below:

concatenation of the following values:

 String body of the encrypted fields

Encrypted payload

{"data":[{"requestID":"1","ipoID":"

 X-FINI-REQUEST-ID

1234","idList":[{"idType":"%enc_

 X-FINI-TIMESTAMP

%eapFkonN3fzIDdSEkiD9EQg=

","idCountryJurisdiction":"%enc_

The signature should then be encrypted

%ACzvoa5ZmoiXFScyhNbRKtx

under the following configurations:

Ugw==","idNum":"%enc_%BVeZ

9hPEphW7EeSiE2UMP6bnM/Q

Configuration

Value

bklYusbM=","fullNameEng":"%e

Algorithm

HMACSHA256

nc_%CQnGpkKS/FHrGOMgkJR

Signature Key

Data Key from

OsmXZe+kEXEZ61hEcNn/P","fu

Section 3.2.1

llNameChi":"%enc_%rtYCIbx0d

Zksk9K1QLpNT3zAjRi2YaZuW

Q=="}],"appQuantity":"1000","fir

mID":"00000","ownRef":"f992b5c

2-fd16-4e57-8387-

738cb7aa75fb"}]}

X-FINI-REQUEST-ID

26219512b1da421eafc8560638f

f69af

X-FINI-TIMESTAMP

1641264153182

Header value (after

JcKBK3rJwmVlqjKE7+EisQps

hasing and

u4KNtHt3Mzrwtx+0Q4E=

encryption)

X-FINI-ENCRYPTION-

A field to indicate the request includes an

YES

CLIENT

encrypted payload.

If the request doesn’t include an encrypted

payload, the header is not required.

Java implementation sample source code for generating X-FINI-ENCRYPTED-KEY header

//Concatenation of Data Key and IV (delimited by #), X-FINI-ENCRYPTED-KEY

String e_key_str = dataKeyBase64Str + "#" + ivBase64Str;

// Generate X-FINI-ENCRYPTED-KEY header

Cipher cipher = Cipher.getInstance("RSA");

cipher.init(Cipher.ENCRYPT_MODE, getPublicKey(publicKeyFINI));

byte[] eBytes = cipher.doFinal(e_key_str.getBytes());

String X_FINI_ENCRYPTED_KEY = Base64.getEncoder().encodeToString(eBytes);

Java implementation sample source code for generating X-FINI-SIGNATURE header

// Generate X-FINI-SIGNATURE header

String algorithm = "HMACSHA256";

byte[] keyBytes = Base64.getDecoder().decode(dataKeyBase64Str);

Key key = new SecretKeySpec(keyBytes, 0, keyBytes.length, algorithm);

Mac mac = Mac.getInstance(algorithm);

mac.init(key);

String X_FINI_SIGNATURE = Base64.getEncoder().encodeToString(mac.doFinal((payload + requestID + timestamp) .getBytes()));

3.3 Decrypting API Responses

This section covers the step-by-step workflow for decrypting API responses containing encrypted data fields

3.3.1 Verify Signature

Before decrypting any fields, you should verify signature first. Compare Local Signature ("localSignature") and

Remote Signature ("remoteSignature"), if the 2 signatures do not match, it indicates a tampered response.

Field

Description

Sample

localSignature

Computed by signing the response body using

ij0GF6CE7RK2KDPL39UxvxBMSYdQth1M5RpCihQUIm

HMACSHA256, with the Data Key (Section

3.1.2) as the signature key

remoteSignature

Obtain the value from response header X-FINI-

ij0GF6CE7RK2KDPL39UxvxBMSYdQth1M5RpCihQUIm

SIGNATURE

3.3.2 Decrypt Response Body

An API response with the field "X-FINI-ENCRYPTION-SERVER" implies a response body with encrypted fields.

Sample response from the 7.4 Enquire EIPO Subscription Entries API endpoint (red text = encrypted fields):

{

"code": "0",

"message": "",

"data": [{

"stkCode": "9988",

"isin": "KYG017191142",

"status": "25",

"subFlowStatus": "3",

"recordID": "2462303930948573A ",

"idList": [{

"idType": "%enc_%eapFkonN3fzIDdSEkiD9EQg=",

"idCountryJurisdiction": "%enc_%ACzvoa5ZmoiXFScyhNbRKtxUgw==",

"idNum": "%enc_%CVaa9BTCphW3EeMJV/bYQyR4JnsJbluxoAI=",

"fullNameEng": "%enc_%Cw/JqQCj8VSuddUvgb64LzNdhVcNoMVtvs2a+w==",

"fullNameChi": "%enc_%of4bIoRQdqsJKkXZ1yd4okbiVffjc4oMhg=="

}],

"appQuantity": "1000",

"allotQuantity": "100",

"firmID": "00000",

"ownRef": null,

"unsuccessfulReason": "0",

"intDuplicateIndicator": "0",

"exception": []

}

"totalSize": 1,

"timestamp": "2021-08-26 12:30:29",

"nextCursor": "0",

"exception":[]

}

Each encrypted field should have its prefix "%enc_%" removed, then decrypted using the Data Key and IV (Section

3.1.2) with the following configurations:

Configuration

Value

Algorithm

AES

Mode

GCM

Padding

NoPadding

Worked example using the "fullNameEng" field (red text = encrypted value):

Encrypted field in API response

"fullNameEng":"%enc_%Cw/JqQCj8VSuddUvgb64LzNdhVcNoMVtvs2a+w=="

Encrypted value

Cw/JqQCj8VSuddUvgb64LzNdhVcNoMVtvs2a+w==

Decrypted Value

Chan Tai Man

Java implementation sample source code

// Decrypt data field

SecretKeySpec secretKeySpec = new SecretKeySpec(dataKey.getEncoded(), "AES");

Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");

cipher.init(Cipher.DECRYPT_MODE, secretKeySpec, ivKey);

String encryptedTextValue = Base64.getDecoder().decode(encryptedTextValueBase64);

byte[] decryptedByteArray = cipher.doFinal(encryptedTextValue);

String decryptedValue = new String(decryptedByteArray);

3.4 End-to-End Encryption Error Codes and Messages

If the encryption API request is not submitted correctly with the required headers or data, errors will occur during end-

to-end encryption or decryption processing in FINI. The following is a list of error codes and messages which may be

returned in FINI API response due to incorrect encryption API request:

Code

Message

411001

Missing X-FINI-REQUEST-ID in the header

411002

Duplicate Request ID

411003

Missing X-FINI-TIMESTAMP in the header

411004

Request timestamp expired

411005

Missing X-FINI-SIGNATURE in the header

411006

Missing X-FINI-ENCRYPTED-KEY in the header

411007

Public key is wrong, FINI can't decrypt the encrypted key, please re-fetch crypto meta

411008

Signature error

411009

No such field {json_key}

411010

Cipher text format is wrong

411011

FINI can't decrypt the cipher text of the field {json_key}

411999

Crypto process exception

4 Formats and Conventions

4.1 Identifiers

4.1.1 IPOs



IPOs are identified using an ipoID ("ipoID"), which is different from an IPO’s Stock Code ("stkCode") or ISIN ("isin").

The design is intended to avoid situations where Stock Codes and ISINs are being reused, e.g. an IPO relaunching

under different IPO cases within a short period of time. The use of ipoIDs is unique to the FINI API Gateway, and

the identifiers can be queried through the Enquire IPO List API endpoint.

/api/ipos/refdata/v1?ipoID=1234

4.1.2 EIPO Subscriptions



EIPO subscriptions are identified using a Record ID ("recordID"), which is a globally unique reference number

generated by the system upon successful validation and submission. It contains: (i) a 16-digit integer; and (ii) a

suffix indicating the method through which the subscription is created.⁴

/api/eipo/subscriptions/query/v1?recordID=2486466216549731A

4.1.3 EIPO Funding



Each HKSCC Participant’s EIPO subscription list within an IPO is identified using a Transaction Reference

("transactionRef"). Each reference is a globally unique reference number generated by the system upon an HKSCC

Participant making a first subscription within an IPO. It contains a 13-digit integer.

/api/eipo/funding/query/v1?transactionRef=5224703318532

⁴ "O" = Online input, "B" = Bulk upload, and "A" = API.

4.2 Data Formats

All request and response fields are determined by a data type and max length:

Type

Length

Description

Example

String

[n]

Field with alphanumeric characters of n

Request field "fullName" has the following parameters:

characters, fully UTF-8 encoded. ⁽¹⁾

Format

Length

String

Successful examples:

 "fullName":"David Chan Tai Man"

 "fullName":"陳大文"

Unsuccessful examples:

 "fullName":"David Chan Tai Man FOO" (exceeds length)

 "fullName":"David Chan Tai Man " (invalid character)

Integer

[n]

Field with numeric characters of up to n

Request field "pageSize" has the following parameters:

digits.

Format

Length

The FINI API Gateway supports all

Integer

unsigned 64-bit integers, with a range

between 0 and 18446744073709551615.

Successful examples:

 "pageSize":9

Certain numeric fields are classified as

string, as their sizes may

 "pageSize":18446744073709551614

Unsuccessful examples:

 "pageSize":18446744073709551616 (overflow)

 "pageSize":-1 (underflow)

Decimal

[n1],[n2]

Field with an integer component (n1 - n2)

Request field "priceMax" has the following parameters:

and a decimal component (n2),

separated by a comma.

Format

Length

Decimal

12,3

The decimal component (n2) is the max

number of digits after the separator.

Numerical range:

 Min: 0.000

The integer component (n1) - the decimal

component (n2) is the max number of

 Max: 999999999.999

digits before the separator/

Array

[n]

Field holding n variables, separated by

Request field "idList" has the following parameters:

commas (",") and enclosed by square

brackets ("[" and "]")

Field

Format

Length

idList

Array

1.1

idType

String

1.2

idNum

String

Successful example:

"idList":[

{"idType":"2",

"idNum":"GJ377364"},

{"idType":"2",

"idNum":"RQ347486"}

]

Unsuccessful example:

"idList":[

{"idType":"2",

"idNum":"GJ377364"},

{"idType":"2",

"idNum":"RQ347486"},

{"idType":"2",

"idNum":"XX323346"}

]

(1) Unless specified, the all UTF-8 characters should be accepted, with the exception of the following characters / character sets:

Unicode

Description

1F000-1F02F

Mahjong Tiles

1F030-1F09F

Domino Tiles

1F0A0-1F0FF

Playing Cards

1F100-1F1FF

Enclosed Alphanumeric Supplement

1F200-1F2FF

Enclosed Ideographic Supplement

1F300-1F5FF

Miscellaneous Symbols and Pictographs

1F600-1F64F

Emoticons (Emoji)

1F650-1F67F

Ornamental Dingbats

1F680-1F6FF

Transport and Map Symbols

1F700-1F77F

Alchemical Symbols

1F780-1F7FF

Geometric Shapes Extended

1F800-1F8FF

Supplemental Arrows-C

1F900-1F9FF

Supplemental Symbols and Pictographs

1FA00-1FA6F

Chess Symbols

1FA70-1FAFF

Symbols and Pictographs Extended-A

1FB00-1FBFF

Symbols for Legacy Computing

E0000-E007F

Other official incorporation document

Broker-to-Client Assigned Number

3.6.2

idCountryJurisdiction

String

The issuing authority of the applicant’s identification document. Based on ISO-

3166 Alpha-3 codes, or ‘OTH’ to represent "Other".

3.6.3

idNum

String

The ID number of the applicant’s identification document.

3.6.4

fullNameEng

String

150

The full English name of the applicant.

3.6.5

fullNameChi

String

150

The full Chinese or non-English name of the applicant.

3.7

appQuantity

String

The number of securities being subscribed by the applicant

3.8

allotQuantity

String

The number of securities allotted to the applicant.

3.9

firmID

String

The SEHK Participant ID for identifying the recipient of any brokerage fees.

3.10

ownRef

String

Free text field for own reference.

3.11

unsuccessfulReason

String

To indicate the applicable reason for which the subscription was unsuccessful,

expressed in reason codes:

ID Type

Description

Allotted

Not allotted

Failed pre-funding

Duplicate application

Incomplete information

Invalid BCAN

EIPO default

Others

3.12

intDuplicateIndicator

String

If the subscription has been identified as a duplicate within the HKSCC

Participant’s subscription list, then "1". Else, the response will return "0".

3.13

exception

Array

To indicate whether an individual request has failed any validation checks:

 Empty array = the individual request has passed all validation checks

 Non-empty array = the individual request has a single or multiple errors,

with each error expressed as an individual object

3.13.1

recordErrorCode

String

3.13.2

recordErrorMsg

String

100

totalSize

Integer

Total size of the API response.

timestamp

String

Timestamp of the API response, in YYYY-MM-DD HH:MM:SS.

nextCursor

String

The key reference (recordID) immediately after the final result of response. If

there are no further records, "0" will be returned.

exception

Array

To indicate whether the entire request failed any structural or permission-

related validation checks:

 Empty array = no structural or permission-related error(s) were identified

across the entire request

 Non-empty array = the entire request was rejected due to a single or

multiple structural or permission-related error(s), with each error expressed

as an individual object

7.1

recordErrorCode

String

7.2

recordErrorMsg

String

100

{

"code": "0",

"message": "",

"data": [{

"stkCode": "9988",

"isin": "KYG017191142",

"status": "25",

"subFlowStatus": "3",

"recordID": "2462303930948573A ",

"idList": [{

"idType": "1",

"idCountryJurisdiction": "HKG",

"idNum": "A123456(9)",

"fullNameEng": "Chan Tai Man",

"fullNameChi": "陳大文"

{

"idType": "1",

"idCountryJurisdiction": "HKG ",

"idNum": "B234567(1)",

"fullNameEng": "Chan Siu Man",

"fullNameChi": "陳小文"

{

"idType": "1",

"idCountryJurisdiction": "HKG ",

"idNum": "B234567(1)",

"fullNameEng": "Mary Lee Sum See",

"fullNameChi": "李心思"

}],

"appQuantity": "1000",

"allotQuantity": "100",

"firmID": "00000",

"ownRef": null,

"unsuccessfulReason": "0",

"intDuplicateIndicator": "0",

"exception": []

{

"stkCode": "9988",

"isin": "KYG017191142",

"status": "25",

"subFlowStatus": "3",

"recordID": "4317515259216099A ",

"idList": [{

"idType": "4",

"idCountryJurisdiction": "OTH",

"idNum": "A1B200D4E5F6G7H8I9J0",

"fullNameEng": "Alpha Company Ltd",

"fullNameChi": "甲有限公司"

}],

"appQuantity": "5000",

"allotQuantity": "500",

"firmID": "00000",

"ownRef": null,

"unsuccessfulReason": "0",

"intDuplicateIndicator": "0",

"exception": []

{

"stkCode": "9988",

"isin": "KYG017191142",

"status": "25",

"subFlowStatus": "3",

"recordID": "5365467074774676A ",

"idList": [{

"idType": "1",

"idCountryJurisdiction": "HKG",

"idNum": "C345678(A)",

"fullNameEng": "",

"fullNameChi": "Rémy Victor"

}],

"appQuantity": "500000",

"allotQuantity": "50000",

"firmID": "00000",

"ownRef": null,

"unsuccessfulReason": "0",

"intDuplicateIndicator": "0",

"exception": []

}],

"totalSize": 3,

"timestamp": "2021-08-26 12:30:29",

"nextCursor": "0",

"exception":[]

}

8 EIPO Funding

8.1

Enquire EIPO Funding

8.1.1

Request

POST

/api/eipo/funding/query/v1

Field

Type

Length

Required

Description

data

Object

Yes

1.1

ipoID

String

Must be a valid ipoID from the Enquire IPO List API endpoint. Mandatory

if transactionRef [Field #1.2] = null or blank.

1.2

transactionRef

Array

1000*1

Must be a valid transactionRef assigned to the HKSCC Participant’s EIPO

subscriptions within an IPO. Mandatory if ipoID [Field #1.1] = null or

String

blank.

1.3

preFundingStatus

String

Sub-flow status of the Transaction Reference, expressed as status codes:

Code

Description

Pending

Not Applicable

Confirmed

Rejected

Invalidated

During the public offer book open (before the Pre-funding Requirement is

finalised), this field returns as null.

size

Integer

Expected page size of the API response. Must be between 1 and 1,000. If

null or blank, default as 100.

nextCursor

String

Yes

Timestamp of the API response, in YYYY-MM-DD HH:MM:SS format.

{

"data": {

"ipoID":"1234",

"transactionRef": [],

"preFundingStatus": null

"size": 100,

"nextCursor": "0"

}

{

"data": {

"ipoID":"1234",

"transactionRef": ["1241677736293","1614124660146","4557626203254"],

"preFundingStatus": null

"size": 100,

"nextCursor": "2244"

}

{

"data": {

"ipoID":"1234",

"transactionRef": ["1241677736293","1614124660146","4557626203254"],

"preFundingStatus": "10"

"size": 100,

"nextCursor": "5835245508721"

}

8.1.2

Response

Field

Type

Length

Description

code

String

0 to indicate ‘successful response’.

message

String

100

Empty string, i.e. "" to indicate successful response.

data

Array

3.1

ipoID

String

A unique, sequentially-generated value assigned to each IPO case stored on

FINI. Used as the identifier for IPOs within the FINI API Gateway.

3.2

stkCode

String

The IPO’s stock code.

3.3

isin

String

The IPO’s ISIN.

3.4

status

String

The status of the IPO, expressed in status codes:

Status

Description

Deal Initiated

Public Offer Closed

Application Validated

Allotment Confirmed

Money Settlement

Allocation Confirmed

Placing Approved

Allotment Results Approved

Trading Started

Suspended

Cancelled

3.5

transactionRef

String

The Transaction Reference assigned to the HKSCC Participant’s EIPO

subscriptions within the IPO.

3.6

preFundingStatus

String

Sub-flow status of the Transaction Reference, expressed as status codes:

Code

Description

Pending

Not Applicable

Confirmed

Rejected

Invalidated

During the public offer book open (before the Pre-funding Requirement is

finalised), this field returns as null.

3.7

settlementStatus

String

Settlement status of the Transaction Reference, expressed as status codes:

Code

Description

Pending

Not Applicable

Settled

Rejected

Defaulted

Before the public offer allotment is made available, this field returns as null.

3.8

ipoInfo

Object

3.8.1

tradeCurrency

String

The IPO’s trading currency, expressed as currency codes:

Currency

Description

HKD

Hong Kong Dollar

CNY

Chinese Yuan

USD

United States Dollar

3.8.2

priceMin

Decimal

12,3

The minimum offer price of the IPO.

3.8.3

downwardPriceFlex

Decimal

3,0

The percentage at which the IPO company may price its IPO below the

minimum offer price. Example: "10" = 10%.

3.8.4

priceFloor

Decimal

12,3

The lowest possible price for the IPO, calculated as priceMin * (1 -

downwardPriceFlex).

3.8.5

priceMax

Decimal

12,3

The maximum offer price of the IPO.

3.8.6

priceFinal

Decimal

12,3

The final offer price of the IPO.

3.8.7

poMaxValue

Decimal

20,2

The highest value the IPO company is able to allocate to the public offer.

3.8.8

prefundingDate

String

The date for confirming the HKSCC Participants’ pre-funding requirements.

3.9

fundingInfo

Object

3.9.1

partID

String

The HKSCC Participant’s ID within CCASS.

3.9.2

partName

String

The HKSCC Participant’s company short name.

3.9.3

poMaxOptIn

String

To indicate whether the HKSCC Participant has opted in to poMax for the pre-

funding requirement calculations. "Y" = Yes, "N" = No.

3.9.4

totalAppQuantity

String

The total number of securities subscribed by the HKSCC Participant within the

IPO.

3.9.5

appValue

Decimal

20,2

The total value of securities subscribed by the HKSCC Participant within the

IPO.

3.9.6

prefundingReq

Decimal

20,2

The HKSCC Participant’s pre-funding requirement. If the HKSCC Participant’s

poMaxOptIn = "Y", then it is calculated as the lower figure between poMax

Value and appValue. If the HKSCC Participant’s poMaxOptIn = "N", then it is

the appValue.

3.9.7

totalAllotQuantity

String

The total number of securities allotted to the HKSCC Participant within the IPO.

3.9.8

allotValue

Decimal

20,2

The total value of securities allotted the HKSCC Participant within the IPO.

3.10

bankAccInfo

Object

3.10.1

cpBankCode

String

The bank code of the HKSCC Participant’s designated bank account from

which the pre-funding requirement should be transferred.

3.10.2

cpBranchCode

String

The branch code of the HKSCC Participant’s designated bank account from

which the pre-funding requirement should be transferred.

3.10.3

cpBankAcctNum

String

The bank account number of the HKSCC Participant’s designated bank

account from which the pre-funding requirement should be transferred.

3.10.4

nomBankCode

String

The bank code of the EIPO Designated Bank’s nominee bank account to which

the pre-funding requirement should be transferred.

3.10.5

nomBranchCode

String

The branch code of the EIPO Designated Bank’s nominee bank account to

which the pre-funding requirement should be transferred.

3.10.6

nomBankAcctNum

String

The bank account number of the EIPO Designated Bank’s nominee bank

account to which the pre-funding requirement should be transferred.

3.11.7

debtorRef

String

The debtor reference of the EIPO Designated Bank’s nominee bank account to

which the pre-funding requirement should be transferred.

3.11

exception

Array

To indicate whether an individual request has failed any validation checks:

 Empty array = the individual request has passed all validation checks

 Non-empty array = the individual request has a single or multiple errors,

with each error expressed as an individual object

3.11.1

recordErrorCode

String

3.11.2

recordErrorMsg

String

100

totalSize

Integer

Total size of the API response.

timestamp

String

Timestamp of the API response, in YYYY-MM-DD HH:MM:SS format.

nextCursor

String

The key reference (transactionRef) immediately after the final result of

response. If there are no further records, "0" will be returned.

exception

Array

To indicate whether the entire request failed any structural or permission-

related validation checks:

 Empty array = no structural or permission-related error(s) were identified

across the entire request

 Non-empty array = the entire request was rejected due to a single or

multiple structural or permission-related error(s), with each error expressed

as an individual object

7.1

recordErrorCode

String

7.2

recordErrorMsg

String

100

{

"code": "0",

"message": "",

"data": [{

"ipoID": "1234",

"stkCode": "9988",

"isin":"KYG017191142",

"status": "25",

"transactionRef": "1241677736293",

"preFundingStatus": "10",

"settlementStatus": null,

"ipoInfo": {

"tradeCurrency": "HKD",

"priceMin": 0.000,

"downwardPriceFlex": 0,

"priceFloor": 0.000,

"priceMax": 188.000,

"priceFinal": 176,

"poMaxValue": 10449004280.00,

"prefundingDate": "2020-09-30"

"fundingInfo": {

"partID": "B01130",

"partName": "BOCI SECURITIES",

"poMaxOptIn": "Y",

"totalAppQuantity": "1000000",

"appValue": 208980085.60,

"prefundingReq": 208980085.60,

"totalAllotQuantity": null,

"allotValue": null

"bankAccInfo": {

"cpBankCode": "012",

"cpBranchCode": "001",

"cpBankAcctNum": "929874231",

"nomBankCode": "012",

"nomBranchCode": "004",

"nomBankAcctNum": "612352324",

"debtorRef": "ABCEDFGH"

"exception": []

{

"ipoID": "1234",

"stkCode": "9988",

"isin":"KYG017191142",

"status": "25",

"transactionRef": "1614124660146",

"preFundingStatus": "10",

"settlementStatus": "",

"ipoInfo": {

"tradeCurrency": "HKD",

"priceMin": 0.000,

"downwardPriceFlex": 0,

"priceFloor": 0.000,

"priceMax": 188.000,

8.2

Confirm EIPO Funding

8.2.1

Request

POST

/api/eipo/funding/confirm/v1

Field

Type

Length

Required

Description

data

Array

Yes

Min 1 object, max 1,000 objects. Each object should contain 1

subscriptions (i.e. each request may process up to 1,000 subscriptions).

1.1

transactionRef

String

Yes

Must be a valid Transaction Reference with a preFundingStatus = "10"

1.2

preFundingStatus

String

Yes

The target pre-funding status to be amended by the API request.

Status

Description

Confirm pre-funding

Reject pre-funding

{

"data": [{

"transactionRef": "6398340114921",

"preFundingStatus": "20"

{

"transactionRef": "6398340114936",

"preFundingStatus": "20"

{

"transactionRef": "6398340114947",

"preFundingStatus": "20"

{

"transactionRef": "6398340114959",

"preFundingStatus": "20"

{

"transactionRef": "6398340114972",

"preFundingStatus": "30"

}

]

}

8.2.2

Response

Field

Type

Length

Description

code

String

0 to indicate ‘successful response’.

message

String

100

Empty string, i.e. "" to indicate successful response.

data

Array

3.1

transactionRef

String

The transactionRef from the original API request.

3.2

preFundingStatus

String

The latest preFundingStatus after processing the API request.

3.3

exception

Array

To indicate whether an individual request has failed any validation checks:

 Empty array = the individual request has passed all validation checks

 Non-empty array = the individual request has a single or multiple errors,

with each error expressed as an individual object

3.31

recordErrorCode

String

3.32

recordErrorMsg

String

100

totalSize

Integer

Total size of the API response.

timestamp

String

Timestamp of the API response, in YYYY-MM-DD HH:MM:SS format.

exception

Array

To indicate whether the entire request failed any structural or permission-

related validation checks:

 Empty array = no structural or permission-related error(s) were identified

across the entire request

 Non-empty array = the entire request was rejected due to a single or

multiple structural or permission-related error(s), with each error expressed

as an individual object

6.1

recordErrorCode

String

6.2

recordErrorMsg

String

100

{

"code": "0",

"message": "",

"data": [{

"transactionRef": "6398340114921",

"preFundingStatus": "20",

"exception": []

{

"transactionRef": "6398340114936",

"preFundingStatus": "20",

"exception": []

{

"transactionRef": "6398340114947",

"preFundingStatus": "20",

"exception": []

{

"transactionRef": "6398340114959",

"preFundingStatus": "20",

"exception": []

{

"transactionRef": "6398340114972",

"preFundingStatus": "30",

"exception": []

}

"totalSize": 5,

"timestamp": "2021-09-30 11:55:21",

9 FAQs for External User Testing (EUT) & Production

9.1

FINI API Connectivity

How to ensure the connectivity to FINI API Gateway is successful after VPN is established?

Any typical browser request on the EIPO Listing API endpoint without JWT can get a JSON return.

EUT: https://fini.u4cp.hkex.com.hk/api/ipos/list/v1

Production: https://fini.hkex.com.hk/api/ipos/list/v1

{

"code" : "1G001",

"message" : "Bad Parameter Input",

"data" : [ ],

"totalSize" : 0,

"timestamp" : "2023-02-14 11:24:38",

"exception" : [ ]

}

Where can the Participants input/maintain Agent profile and Machine profile information for JSON Web

Token (JWT)?

EUT: https://connect.u4cp.hkex.com.hk

Production: https://connect.hkex.com.hk

Under Support -> Manage Access Rights

Why does Development Tool Postman / Browser return invalid SSL in EUT environment when

accessing the FINI API endpoints?

Self-signed CA Certificate approach is used for EUT, participants can suppress the SSL checking in the

setting of Postman and accept the SSL warning from Browser. API program should also accept the self-

signed CA certificate when connecting to FINI API Gateway.

Can I use IP address instead of domain name for the API requests?

No. FINI will reject API request accessing by IP address.

Can I perform load/performance testing on FINI EUT or Production environment?

No. There is throttle control, participants will find their IP is blocked and restricted to access FINI APIs.

9.2

FINI API Authentication

1. Does FINI API support SAML authentication?

No. FINI API uses OATH2.0 for authentication.

2. How to generate public and private key pair set for testing purpose?

Developer is recommended to use self-developed application for public and private key pair set generation.

For quick testing purpose, there are also free resources from the internet for public and private key pair

generation.

e.g.

https://mkjwk.org/

Corresponding Key parameter requirement

Key Size: 2048

Key Use: Signature

Algorithm: RS256

Key ID: SHA-256

Show X.509: Yes

3. How do the Participants update their Key (Key Rotation every year) without application outage?

Both Agent Profile and Machine Profile allow at most two key pairs to be registered and used

simultaneously. Participants can consider updating one by one to minimize impact.

4. Can multiple program instances use the same JWT (from HKEX AM) for API requests?

Not recommended.

5. What is the JWT (from HKEX AM) expiry time?

The JWT expiry time is 30s.

9.3 EIPO Subscription Entries APIs encryption

1. Why does JAVA SecureRandom.getInstanceStrong() that recommended by the API Workshop unable to

work on Linux environment?

The SecureRandom.getInstanceStrong() works on Windows platform only, please consider using

SecureRandom.getInstance("NativePRNGNonBlocking") on Linux.

2. What is the reason of error message “Crypto process exception”?

Please check if encryption has been done for the following two API endpoints on Personal Data fields

according to the API Specification.

api/eipo/subscriptions/add/v1

api/eipo/subscriptions/change/v1

As long as no personal data should be encrypted for Enquire/Invalidate EIPO Subscription Entries

APIs, what is the reason of having error message “Crypto process exception”?

Please check X-FINI-ENCRYPTION-CLIENT in HTTP header, which must be set to "N" for

Enquire/Invalidate EIPO.

How often is the changing of public Key from Crypto Metadata Request API?

The public key may be changed/updated from time to time without notification. Please retrieve the key for

every single request that requires encryption.

9.4

FINI API endpoint validation

What is the reason for always getting Signature Error for EIPO Subscription Entries API?

Please ensure the 3 major components must be included for the Signature calculation.

Payload + Request ID + Timestamp

What is the reason always getting Signature Error when I use development tool Postman for all

encryption needed APIs?

Postman probably adds additional line break for the input payload, this makes discrepancy between the

Signature calculation value. Developer should ensure the Signature calculation on the payload is identical

to the Postman submitted one.

What is the reason of error message “Bad Parameter Input”?

If the input JSON payload (POST Request) fails to pass the basic syntax validation leading FINI cannot

parse the JSON content OR missing mandatory parameters in the endpoint URL(GET Request). Then the

general validation message “Bad Parameter Input” will be found, thus the whole API request will be rejected.

What if requestID value is duplicated in the same Add EIPO Subscription Entries API request?

All the particular duplicated records in the request will be rejected, other records with unique requestID will

be handled as usual.

Can I use same requestID value in different Add EIPO Subscription Entries API requests?

Yes. The duplication checking on requestID only happens in the same Add EIPO Subscription Entries API

request.

Will the whole Add EIPO Subscription Entries API request be rejected if there is certain number of

records are invalid?

No. FINI will reject only those invalid records, if the whole Add EIPO Subscription Entries API request can

pass the basic syntax validation.

What will happen if the same EIPO applicant content was submitted by the same/different Add EIPO

Subscription Entries API requests from the same CP?

There is no immediate EIPO application duplication checking on the Add EIPO Subscription Entries API

request. All those requests, having duplications, will be submitted and recorded in FINI but the flag

intDuplicateIndicator will be updated as “1” from Enquire EIPO Subscription Entries endpoint return. In case

no further action is taken by CP, all duplicated records will be rejected only on the EIPO Public Offer Close

Day.

What will happen if the same EIPO applicant content was submitted by different CPs?

The duplicated records will be rejected on the EIPO Public Offer Close Day.

Is there any full list of FINI validation can be provided?

There is no FINI validation full list for the public, participants have to retrieve the validation error message

from the JSON response to understand the cause of rejection.

Generally, participants can check the HTTP response value (Section 2.4.2) to determine the follow up

action. HTTP 200 with JSON response is usually related business validation. IT team should follow up for

other HTTP response values like 400, 403, 404..etc.

9.5

Miscellaneous

Why does FINI always return “Authorization in Input JSON is EMPTY”?

Please use protocol HTTP 1.1 instead of HTTP 2.0

What encoding should be used for the Chinese Name in the EIPO Subscription Entries?

UTF-8

I am using encoding UTF-8 as input source however the Chinese Characters still cannot be recorded by

FINI correctly. Unexpected Characters are found in the EIPO Subscription Entries result.

If participants use JAVA for their application development, please ensure the JVM handles the input source

UTF-8 flawlessly by checking if the JVM starts with parameter “-Dfile.encoding=UTF-8”.

Is it a must to verify the remote Signature in HTTP Header X-FINI-SIGNATURE?

This is our recommendation for the Participants to detect if any tampered response.

What is the purpose of Enquire EIPO Funding API?

If FINI BANK users would like to exercise the EIPO Funding Confirmation, corresponding record

transactionRef is the mandatory value that can only be obtained via Enquire EIPO Funding API.

What should be done if there is “Time Out”/”No Response” situation for Add EIPO Subscription Entries

API request? Should I re-submit immediately?

Users have to verify if corresponding API requests are received and processed by FINI via FINI Portal (IPO

Card) or Enquire EIPO Subscription Entries API (by ipoID) before any re-try/re-submit action.

All those requests, having duplications, will be submitted and recorded in FINI but rejected only on the EIPO

Public Offer Close Day. Please refer to Section 9.4 Q7.

Can I retrieve applicant’s allotment result via Enquire EIPO Subscription Entries API?