Public Tech Platform for Frictionless Credit

eKYC API Specification

Document Version 1.2

December 2023

RESERVE BANK INNOVATION HUB, BANGALORE

Revision History

Revision Revision Date Author API Version Summary of Changes Changes marked
Number
1.0 31st Mar 2023 RBIH 1.0 First version
1.1 27th Jun 2023 RBIH 1.0 Response correction

1.1.5 30th Oct 2023 RBIH 1.0 Boilerplate

Implementation

1.2 12th Dec 2023 RBIH 1.2 API Version changed

Customer Support
For technical support, please contact the Platform support center (PSC).

Support email address [email protected]

We respond within 2 hours during business hours (8 am to 8 pm IST)
Table of Contents

1 INTRODUCTION .............................................................................................................................. 4

2 OBJECTIVE OF THIS DOCUMENT ............................................................................................... 4

3 PREREQUISITES .............................................................................................................................. 4

3.1.1 IP WHITELISTING ........................................................................................................................................... 4

3.1.2 URL WHITELISTING ....................................................................................................................................... 4
3.1.3 PLATFORM CREDENTIAL GENERATION........................................................................................................ 5
3.1.4 SERVICE SUBSCRIPTION.................................................................................................................................. 5
3.1.5 TOKEN GENERATION ...................................................................................................................................... 5

4 API ENDPOINT................................................................................................................................. 6

4.1 SERVICE URL.................................................................................................................................... 6

4.1.1 URLS................................................................................................................................................................. 6
4.1.2 REQUEST TYPE ................................................................................................................................................. 6
4.1.3 URL PARAMETER ............................................................................................................................................ 6

5 API HTTP HEADERS....................................................................................................................... 6

5.1 PAYLOAD SCHEMA ............................................................................................................................ 7

6 API RESPONSE ................................................................................................................................. 8

6.1 SERVICE RESPONSE ........................................................................................................................... 8

7 ERROR CODES.................................................................................................................................. 9

8 SUPPORT ........................................................................................................................................... 9

eKYC API Specification Pg| 3

1 Introduction
The Electronic Know Your Customer or eKYC API is a digital process used by businesses
and organizations to verify the identity of individuals remotely or online. It is a paperless
and electronic alternative to traditional in-person verification methods..

2 Objective of this document

To give an overview of the implementation of the API for technical designers and
developers to refer during system integration.

3 Prerequisites
All the below prerequisites are must before integrating the API with Sandbox and
Production

3.1.1 IP Whitelisting

- Lenders IPs should be Whitelisted with platform.

- This must be done separately for Sandbox and Production.
- An email with the IP Addresses through which the environment will be access need
to be shared to [email protected]
- Platform IPs should also be whitelisted. RBIH Team will share the IPs to whitelist
while onboarding.
- Kindly ensure that the IPs are whitelisted at both ends before testing the API.

3.1.2 URL Whitelisting

- Below are the URLs of Platform that need to be whitelisted in Lenders Network.
- This must be done separately for Sandbox and Production.
- Kindly ensure that the URLs are whitelisted before testing the API.

Non-Prod: Sandbox and UAT Environment

Environment URL
Authentication API service https://auth.nonprod.rbihub.io/

Dev Portal for API catalog and https://am.nonprod.rbihub.io/devportal

Subscription

API Execution for services https://extgw.nonprod.rbihub.io/

Identity Server https://identity.nonprod.rbihub.io/carbon

eKYC API Specification Pg| 4

 Production Environment
Environment URL
Authentication API service https://auth.api.rbihub.io/

Dev Portal for API catalog and https://am.api.rbihub.io/devportal

Subscription

API Execution for services https://extgw.api.rbihub.io/

Identity Server https://identity.api.rbihub.io/carbon

3.1.3 Platform Credential Generation

- Lender should have received the Platform credentials mail with the following
details.
o Public Key
o Client ID
o Client Secret
o User Credentials for Dev portal
o Public Certificates

3.1.4 Service Subscription

- eKYC service should be subscribed in Platform Dev Portal

- This must be done separately for Sandbox and Production.
- Steps to subscribe is available in Latest versions of SOP for Lender Onboarding
document -> Section 10
- The credentials for the Login will be shared to registered Users email.
- Kindly ensure that the Service is subscribed before testing the API.

3.1.5 Token Generation

- JWT token is used for authenticating all Platform APIs.

- To generate JWT Token, you need to have follow the steps mentioned in latest
version of Authentication and Authorization API specification document available in
Platform API Spec folder.
- This must be done separately for Sandbox and Production.
- This token will be valid for 6 hours in Sandbox and 12 hours in production.
- Please ensure you have the latest public key which is shared via email to the user
registered.
- Kindly ensure that the valid token availability before testing the API.

eKYC API Specification Pg| 5

4 API Endpoint
4.1 Service URL

The eKYC Details API is exposed as a stateless API service over HTTPS. Usage of open-
standard data format in JSON (JavaScript Object Notation) and widely used protocol
such as HTTPS will allow easy adoption of the API by lenders.

The API service path provided follows a standard convention:

/{service_name}/{ver}/{lang}

4.1.1 URLs

Sandbox URL https://extgw.nonprod.rbihub.io/ekyc/1.2/en

Production URL https://extgw.api.rbihub.io/ekyc/1.2/en

4.1.2 Request type

Set the request type to GET.

4.1.3 URL parameter

Refer the description of URL Path Parameters below:

URL Parameter Description Value

service name Unique name of the service “ekyc”
ver Current version of API “1.2”
lang Language in which the response is sought. Default “en”
language is English

5 API HTTP Headers

Following headers must be passed in the HTTP request.

Header Description Remarks Example

Parameter
JSON Web Token (JWT) is EkN-
Authenticatio created and signed by DOsnsuRjRO6BxXe
n authentication server upon mmJDm3HbxrbRzX
lender request. glbN2S4sOkopdU4I

eKYC API Specification Pg| 6

Header Description Remarks Example
Parameter
sDxTI8jO19W_A4K
Refer the Authentication and 8ZPJijNLis4EZsHeY
Authorization API 559a4DFOd50_Oqg
specification. HGuERTqYZyuhtF3
9yxJPAjUESwxk2J5
k_4zM3O-
vtd1Ghyo4IbqKKSy
6J9mTniYJPenn5-
HIirE
api-key A unique key is provided by Optional, 434950ee34353tty
the platform to the lender reserved for 33463399
(for future use) during registration for each future purpose.
API. This key is a 24-character
alphanumeric string
consisting of lowercase letters
only
client-id Id in base 64 encoded format Base64 encoded pNRxiviTvgBrf7qM
given by the Platform to the Client Id ANqBVskDYfEa
lender at the time of
registration.
provider Service provider code “106” for Protean
x-env-route Header required to access “/sb” /sb
sandbox environment. Not * only for
required for production sandbox

5.1 Payload Schema

As a policy, the platform will accept all the request message payloads in JSON format
only unless otherwise specified. Every message template will have the following
structure:
{
"meta": {
"ver": "Version of the request template",
"ts": "timestamp in ISO-8601 format e.g. 2023-01-03T21:10:23+05:30",
"txncode": "unique transaction code provided by the lender"
},
"data": {},
"hmac": "SHA-256 Hash of the value of key 'data'"

eKYC API Specification Pg| 7

 }

Key Description
ts Timestamp in ISO-8601 format (yyyy-MM-
ddTHH:mm:ssZ) indicating the time of initiation of
the request

txncode Unique transaction code provided by the lender

ver Version associated with the Service.
data Base64 encoded PID block
hmac SHA-256 hash of the value under the key “data”

6 API Response
6.1 Service response

{
"result": {
"errcode": "E000",
"status": "success",
"info": "eKYC initiated."
},
"data": {
“response”: “<Base64 encoded service provider response>”
},
"signature":
"MEYCIQDoejEHkKtybsE9mZGll7XrFrGMKbTOVEKQi1t6oGJHRAIhAMZbfKoCuOhDPElBqe
RZsc3BhI01Ss11uncvJr558FKv",
"meta": {
"txncode": "412341231",
"ver": "1.2",
"ts": "2023-03-19T07:13:45+0530"
},
"hmac": "LwIMt8MOuX1ui8QpLuAzVQF0qpf/DupFGGZHTzA/am8=",
"publickey":
"MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE2RFeYmyJ8dr7JwELfSn1gzEeP7DKo0uF3xRF
h464ZhkEnuocTS48c0EXfyCsSpDDdwiqUMVbthZzXXSl9gvsmQ==",
"sig-algo": "SHA256withECDSA"
}

eKYC API Specification Pg| 8

The following table provides response parameter details.
Response parameter Description
errcode It’s used to indicate the error code associated with the API
service response. If the response is 'fail status, a relevant
error code will be returned in this field. However, if the
transaction is successful, the value of error code will be
'E000'.
status This field will contain either 'success' or 'failed' depending
on the outcome of the transaction.
signature Digital signature hash of the value located under the key
"data".
txncode Unique transaction code provided by the lender.
ver Indicates the version of the JSON response template that is
currently being used.
ts Indicates the time of initiation of the request in ISO-8601
format as yyyy-MM-ddTHH:mm:ssZ.
hmac SHA256 hash of the value located under the key “data”
publickey Public key of the platform for source verification purposes.
sig-algo This indicates the algorithm used for signing (signature) the
data. For example, SHA256withECDSA.

7 Error Codes
Refer Latest Platform Error Code pdf to get the list of error values.

8 Support
If you are facing any issue, please write to us with the following details.

To: [email protected]

Subject: eKYC API Error

Body:

Service Name: eKYC Service

Environment: Sandbox/Live

eKYC API Specification Pg| 9

Service Provider: Protean

Request Headers:

Request Payload:

Error Code:

Error Message:

Attachment: Screenshot/log of the error

Prerequisites Status:

- IP Whitelisting –
- URL Whitelisting –
- Service Subscription –
- Token Generation -

eKYC API Specification Pg| 10