Application program interface API Version 1 0 Background
Application program interface (API) Version 1. 0
Background • Search and download functionality often used at Financial Institution (FI) front office level (branch end) before onboarding customer. • FIs can search or download KYC details from the CKYC Registry post login using credentials and digital signature. • CKYC registry introduced API services (Application programming Interface) to registered financial institutions for search and download functionality. Note: API services are available for reporting entities internal use only, reporting entity should not extend API services in public domain
Application Programming Interface • An application program interface (API) is code that allows two software programs to communicate with each other. Request Your Application API Response Internet CKYC Application
Application Programming Interface Branch 1 Branch 2 Branch 3 FI Central Server RM 1 • Encrypted Request file • Digitally Signed file • Through Registered IP addresses only Internet Request Response CKYC Application Branch 4 Optional : Secured VPN Tunnel or P 2 P leased line Connectivity
Pre-requisites • API Configuration: o Admin user have access of API configuration page to configure below items: • • • Digital Signature Public Key (. CER format) Public IP* Download CERSAI Public Key *Note: currently CKYC system allows only one IP to configure, will provide option of 5 IPs to be configure shortly
Important points • FI Digital Signature: o Private Key will use for signing API request file o Public Key needs to be upload in CKYC application, system will check authenticity of request file by uploaded public Key of FI • CERSAI Digital Signature: o Pubic Key is available on the CKYC website, this will be use in the request file encryption process • Request and Response Type : Application/XML • API Type: Rest • Multi threading: Available (TBD)
Service URL Search o Testbed: https: //testbed. ckycindia. in/Search/ckycverificationservice/verify o Production: https: //www. ckycindia. in/Search/ckycverificationservice/verify Download o Testbed: https: //testbed. ckycindia. in/Search/ckycverificationservice/download o Production : https: //www. ckycindia. in/Search/ckycverificationservice/download
Request file PID XML Request file Search : ID & Number Download : CKYC number & Date of Birth 256 bit session Key CERSAI public Key FI DSC Private Key <? xml version="1. 0" encoding="UTF-8"? > Step 1: Generate a random 256 bit session key <REQ_ROOT> <HEADER> Step 2: Encrypt PID using this session key by AES <FI_CODE>IN 0001</FI_CODE> PID algorithm <REQUEST_ID>02<REQUEST_ID /> <VERSION>1. 0</VERSION> Encode </HEADER> Encrypted Step 3: Encode the encrypted PID to Base 64 string String (PID) PID <CKYC_INQ> <SESSION_KEY> </REQUEST_ID> Step 4: Encrypt the session key using public key provided Encrypted by CERSAI using RSA algorithm <PID> <PID_DATA> Step 5: Encode the encrypted session key to Base 64 <DATE_TIME /> Encode String Encrypted (Session Key) string Session Key <ID_TYPE /> <ID_NO /> Step 6: Add this encrypted and encoded session key in Encode </PID_DATA> String (PID) request xml </PID> </CKYC_INQ> Encode </REQ_ROOT Step 7: Sign entire request using FI's private key String (PID)
Response file PID XML Response file CERSAI public Key 256 bit session Key FI DSC Private Key Response from CERSAI <REQ_ROOT> Step 1: Verify response file signature using CERSAI’s <HEADER> public key. <FI_CODE>IN 0001</FI_CODE> <REQUEST_ID>02<REQUEST_ID /> /> <VERSION>1. 0</VERSION> Encode Step 2: Parse key parameter from request message </HEADER> String (PID) <CKYC_INQ> <SESSION_KEY> </REQUEST_ID> Encrypted Encode String Step 3: Decode the session key from Base 64 string <SESSION_KEY> BDu 4 Zi 02 ct 0 kxeh. SJyibl. RF 7 Fsjy. Jc 6 e 6 FTze. XPXwm. F 5 n. CMyp. IXMDfx. L+z. Tcopy++6 m. Zm. XPClt. Ir. JF Session Key <PID> (Session Key) M 2 f 9 Gc. P 14 aohnq. Dq. IHy. G 7 WJh. Gel 6 ipgwc. KNEivr. Kbp. Bvzc 5 B 3 CCSDlh 9 WYUVj 6 V 4 </REQUEST_ID> <PID_DATA> <PID> <CKYC_NO /> Step 4: Decrypt encrypted session key using FI’s private Encrypte. BDu 4 Zi 02 ct 0 kxeh. SJyibl. RF 7 Fsjy. Jc 6 e 6 FTze. XPXwm. F 5 n. CMyp. IXMDfx. L+z. Tcopy++6 m. Zm. XPClt. I <NAME /> d key with RSA algorithm <FATHERS_NAME /> r. JFM 2 f 9 Gc. P 14 aohnq. Dq. IHy. G 7 WJh. Gel 6 ipgwc. KNEivr. Kbp. Bvzc 5 B 3 CCSDlh 9 WYUVj 6 V 4 BDu 4 Z <AGE /> i 02 ct 0 kxeh. SJyibl. RF 7 Fsjy. Jc 6 e 6 FTze. XPXwm. F 5 n. CMyp. IXMDfx. L+z. Tcopy++6 m. Zm. XPClt. Ir. JFM 2 Encrypted <PHOTO /> Encode Step 5: Decode the PID from Base 64 string f 9 Gc. P 14 aohnq. Dq. IHy. G 7 WJh. Gel 6 ipgwc. KNEivr. Kbp. Bvzc 5 B 3 CCSDlh 9 WYUVj 6 V 4 BDu 4 Zi 02 ct PID String (PID) <IMAGE_TYPE /> 0 kxeh. SJyibl. RF 7 Fsjy. Jc 6 e 6 FTze. XPXwm. F 5 n. CMyp. IXMDfx. L+z. Tcopy++6 m. Zm. XPClt. Ir. JFM 2 f 9 Gc <KYC_DATE /> P 14 aohnq. Dq. IHy. G 7 WJh. Gel 6 ipgwc. KNEivr. Kbp. Bvzc 5 B 3 CCSDlh 9 WYUVj 6 V 4 BDu 4 Zi 02 ct 0 kxe Step 6: Decrypt data using session key with AES <UPDATED_DATE /> Encryp ted Ph. SJyibl. RF 7 Fsjy. Jc 6 e 6 FTze. XPXwm. F 5 n. CMyp. IXMDfx. L+z. Tcopy++6 m. Zm. XPClt. Ir. JFM 2 f 9 Gc. P 14 a PID ID </PID_DATA> algorithm <</PID> <ERROR /> /> </CKYC_INQ> </REQ_ROOT>
Error Messages Scenario Error Message Digital signature verification failed Incorrect ID type or ID Number Digital signature cannot be verified. Please sign document with proper key Validation failure Request Id size greater than 8 Request Id should not exceed more than 8 digits Request Id is not unique throughout the day for an FI. Request Id is not unique Incorrect FI Code Institution does not exists No records found Time difference between request Time difference should be less than 5 minutes and response is more than 5 minute IP not registered Please configure your IP address. IP does not match with the registered IP The given IP does not match with the institution’s registered IP.
Thank you!! For any clarification / support, please email on helpdesk@ckycindia. in or call on 022 6110 2592
- Slides: 11