REMOTE ACCOUNT ONBOARDING

Table of Contents

Introduction

This is a general walk-through for getting start iAM Smart APIs development of Remote Account Onboarding use case.

Developers of Online Services adopting iAM Smart may find this guide useful when designing and deveoping application flows for remote account onboarding adopting iAM Smart functions.

In this guide we will provide guides on:

  • Setting up your iAM Smart development environment
  • Request anonymous form filling request
  • Obtaining Form filling result

User Journey

Flow

Please find below the sequence diagram for the whole remote account onboarding process:

In this guide, we will focus on some of the key steps that online service and users will be involved into when adopting and using “iAM Smart”.

Click “iAM Smart” Button in initiation page/consent page

Online service shall display one of the following button depends on the scenario:

Scenarios

Online services is required to add a link / button, “More info” or “了解更多” in the initiation page. The link / button shall be linked to the “iAM Smart” thematic webpage based on language preference of user.  The initiation page refers to the page that initiates the “iAM Smart” service, which user clicks the “iAM Smart” button to initiate the interaction with “iAM Smart” mobile application. 

Language

Link

English

https://www.iamsmart.gov.hk/en/

Traditional Chinese

https://www.iamsmart.gov.hk/tc/

Simplified Chinese

https://www.iamsmart.gov.hk/sc/

Submit “Request Anonymous Signing”

Composing Reuqest Body

Parameters Data Type Description
businessID string businessID is a unique identifier for eService to differentiate different request. It should be ASCII string with length less than or equal to 36 chars.
formName string (Optional) The name of the form should be encoded in Unicode. The maximun length can be found in part C of the Appendix in API specification.
formNum string (Optional) The number of the form should be encoded in Unicode. The maximun length can be found in part C of the Appendix in API specification.
formDesc string (Optional) The description of the form should be encoded in Unicode. The maximun length can be found in part C of the Appendix in API specification.
eMEFields array (Conditionally required) Specify the e-Me fields to be requested if eMEFields and profileFields are not provided or are emtpy arrays, HTTP code 200 with error code D20002 will be returned. For available eMEFields please refer to iAM Smart API Specification 6.3.12 or online mockup API.
profileFields array (Conditionally required) Specify the profields fields to be requested if eMEFields and profileFields are not provided or are emtpy arrays, HTTP code 200 with error code D20002 will be returned. For available profileFields please refer to iAM Smart API Specification 6.3.12 or online mockup API.
Your request body should look something like this:  
				
					{

 "businessID": "bbb8aae57c104cda40c93843ad5e6db8",

 "formName": "Example Account Registration Form",

 "formNum": "APP0001",

 "formDesc": "Example Form Description",

 "profileFields": ["idNo", "enName", "gender", "chName", "birthDate"],

 "eMEFields": ["mobileNumber", " emailAddress", "addressDocInfo"]
 
} 
				
			

Encryption

To better protect the data in transit, an additional layer of data encryption will be applied to all APIs POST request (except the one that e-Service request for getting symmetric encryption key).

In this case we will use a mock-up Content Encryption Key (CEK), please find below a base64-encoded mock CEK:

				
					pvD2Zc1mf7tKVh17JOftmzyTaDyVmcULg92nB9qeEoQ=
				
			

Online Service should check whether its CEK is still valid and use it to encrypt all the JSON data of the POST request body as ciphertext using encryption algorithm “AES/GCM/NoPadding”.

This algorithm requires an initialisation vector (“IV”) which is provided by e-Service. The ciphertext, IV and length of IV are then concatenated in the following sequence and BASE64 encoded to formulate the value of JSON name/value pair called “content”.

Content value:

4 bytes IV length + IV + ciphertext

You may refer to the psuedo code below for the encryption implementation:

				
					aes = AES.new(base64.b64decode(CEK), AES.MODE_GCM, IV)
# using AES/GCM/NoPadding for encryption algorithm

byteRequestBody = json.dumps(requestBody, separators=(',', ':')).encode('utf-8')
# request body

encrypted = aes.encrypt(byteRequestBody)
# encrypt the request body

authTag = aes.digest()
# Authentication Tag, based on your programming language it may automatically appeneded to the output of the encryption result

IV_len = (12).to_bytes(4, 'big')
# Length of IV (4 bytes)

body = base64.b64encode(IV_len + IV + encrypted + authTag)
# concatenated IV_len + IV + ciphertext + authTag

return body.decode('utf-8')

				
			
PHP Code Snippets Powered By : XYZScripts.com