Switch to dark theme

Switch to light theme

Create Account Holder

An account holder refers to a real/legal customer to Fusion. Drawing from the real world analogy, an account holder can be an actual person who holds an account at a bank or can be a legal entity like a corporate entity, or merchant. This article lays down the steps fintech shall follow to create an account holder with fusion. Before you begin, it is advised that you familiarize yourself with key Account Holder concepts explained in About Account Holders.

Account Holder Profile Ownership

The Account Holder on-boarded on Fusion has a banking relationship with the Issuer (IFI) that the fintech has partnered with. Therefore, the Issuer determines which details of the Account Holder are accessible by the fintech.

Pre-requisite Information for Account Holder

When an Account Holder is on-boarded on Fusion, typically the below details are required–

  • Personal information, like Full Name, contact information
  • Officially Valid Document (OVD), like Aadhaar number, PAN card, Voter’s ID card, etc.

If you need to collect additional information, Fusion provides custom attributes for this purpose. For example, you can store an Account Holder’s additional mobile number or Unique Customer Identification Code (UCIC) against the application.

Creating Application for Account Holder creation

In order to create a new account holder, first, an Application shall be created for the same on Fusion. The issuer will then review the Application. Once approved by the issuer, the account holder is created with a unique identifier (accountHolderID , individualID). Fintech can then issue the ‘Bundle’ to this account holder.

Note: An applicant may sign up with multiple Fintechs under the same issuer. Zeta system maintains a single identity of an Account Holder per issuer. This is in line with the compliance requirements of the bank and the regulator. This means that if an applicant signs up with multiple fintech’s working with Fusion on the same issuer, there would only be one Account Holder entity.

The fintechs can create an application for the account holder creation using either of the below endpoints.

  • POST /api/v1/ifi/{{ifiID}}/spool/{{spoolid}}/application
  • POST /api/v1/ifi/{ifiID}/applications/newIndividual

The Account Holder’s personal, contact and KYC information shall be then, provided in the request body. Here, Fusion will check for an already existing account holder on the contact number with the IFI.

Note: The /newIndividual API is going to be deprecated soon. Fusion will be using the Applications APIs to create account holders.

Endpoint URI: /application

POST/api/v1/ifi/{{ifiID}}/spool/{{spoolid}}/application
cURL Sample
Switch Theme
Expand More
Copy
curl --location --request POST '{{fusion_base_url}}/api/v1/ifi/{{ifiID}}/spool/{{spoolid}}/application' \
--header 'Content-Type: application/json' \
--header 'X-Zeta-AuthToken: {{token}} \
--data-raw '{
    "requestId": "request_cah-233",
    "vectors": [{
        "type": "e",
        "value": "[email protected]"
    }],
    "sections": {"AccountHolderDetails" : {
        "name": "AccountHolderDetails",
        "type": "CreateRealAccountHolder",
        "details": {
            "individualType": "REAL",
            "dob": {
                "year": 1957,
                "dayOfMonth": 13,
                "month": 7
            },
            "salutation": "Mr.",
            "firstName": "Sarthak",
            "lastName": "Verma",
            "middleName": "Kumar",
            "profilePicURL": "https://s3.amazonaws.com/uifaces/faces/twitter/darylws/128.jpg",
            "applicationType": "CREATE_ACCOUNT_HOLDER",
            "gender": "MALE",
            "mothersMaidenName": "xyz"
        }
    }
    }
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
    "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
    "ifiId": 140793,
    "requestId": "request_cah-233",
    "status": "DATA_CAPTURE_INITIATED",
    "sections": {
        "AccountHolderDetails": {
            "sectionId": "4d62f76d-9826-4b72-a7f5-c3c885e2f6b9",
            "ifiId": 140793,
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "name": "AccountHolderDetails",
            "type": "CreateRealAccountHolder",
            "details": {
                "dob": {
                    "year": 1957.0,
                    "month": 7.0,
                    "dayOfMonth": 13.0
                },
                "gender": "MALE",
                "lastName": "Verma",
                "firstName": "Sarthak",
                "middleName": "Kumar",
                "salutation": "Mr.",
                "profilePicURL": "https://s3.amazonaws.com/uifaces/faces/twitter/darylws/128.jpg",
                "individualType": "REAL",
                "applicationType": "CREATE_ACCOUNT_HOLDER",
                "mothersMaidenName": "xyz"
            },
            "createdAt": "2021-02-19T10:40:04.837+05:30",
            "updatedAt": "2021-02-19T10:40:04.837+05:30"
        }
    },
    "vectors": [
        {
            "vectorId": "d8979db7-bc16-4934-9450-4c33a3991791",
            "ifiId": 140793,
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "type": "e",
            "value": "[email protected]",
            "status": "ENABLED",
            "attributes": {},
            "createdAt": "2021-02-19T10:40:04.707+05:30",
            "updatedAt": "2021-02-19T10:40:04.707+05:30"
        }
    ],
    "stages": [
        {
            "stageId": "2b7c5ecc-64dc-4985-93d8-b1dfb8788de5",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "ASSESSMENT",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2021-02-19T10:40:05.036+05:30",
            "updatedAt": "2021-02-19T10:40:05.036+05:30"
        },
        {
            "stageId": "24691789-c586-49fc-9071-ef5c58066211",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "DATA_CAPTURE",
            "status": "INITIATED",
            "details": {},
            "result": {
                "validationFailed": [
                    {
                        "code": "APPLICATION_SCHEMA_VALIDATION_FAILED",
                        "type": "JsonSchemaValidator",
                        "status": "FAILED",
                        "message": "#: #: only 1 subschema matches out of 2",
                        "attributes": {
                            "errorMessages": [
                                "#/sections: required key [Personal] not found",
                                "#/sections: required key [Vectors] not found"
                            ]
                        }
                    }
                ]
            },
            "createdAt": "2021-02-19T10:40:05.024+05:30",
            "updatedAt": "2021-02-19T10:42:20.436+05:30"
        },
        {
            "stageId": "3546099b-4d81-42d5-abea-05dfbadf50a2",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "ENRICHMENT",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2021-02-19T10:40:05.036+05:30",
            "updatedAt": "2021-02-19T10:40:05.036+05:30"
        },
        {
            "stageId": "11f04481-6e07-4036-b549-69a1868abdfc",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "PROVISIONING",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2021-02-19T10:40:05.036+05:30",
            "updatedAt": "2021-02-19T10:40:05.036+05:30"
        },
        {
            "stageId": "e6163594-0b26-4d96-a890-79231c7adcf4",
            "ifiId": 140793,
            "applicationId": "88d24ca5-2f75-435d-9fed-b6bb0a662377",
            "spoolId": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "name": "REVIEW",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2021-02-19T10:40:05.037+05:30",
            "updatedAt": "2021-02-19T10:40:05.037+05:30"
        }
    ],
    "tags": [
        {
            "type": "spool-id",
            "value": "12b66d97-c5c5-4a38-b896-b1790a6a6845",
            "attributes": {}
        },
        {
            "type": "vbo-id",
            "value": "26c28ca6-4202-464c-9806-b788989762d4",
            "attributes": {}
        }
    ],
    "createdAt": "2021-02-19T10:40:04.672+05:30",
    "updatedAt": "2021-02-19T10:40:05.815+05:30"
}
Code Copied

Endpoint URI: /newindividual

POST/api/v1/ifi/{ifiID}/applications/newIndividual

Input Parameters

ParametersDescription
ifiIDRequired. Unique identifier of the IFI.
formIDOptional. Unique identifier of the form. If specified, value must be unique for each request.
applicationTypeRequired. Type of Application being created. Allowed values: KYC, CREATE_ACCOUNT_HOLDER, EDIT_ACCOUNT_HOLDER. As we are creating an Account Holder, set the value to CREATE_ACCOUNT_HOLDER.
descriptionDescription of the Application. Use the parameter to add comments regarding the Application or the Account Holder.
individualTypeRequired. Type of Account Holder being created. As the Application is for a real account holder , set the value as REAL.
individualIDOptional. Unique identifier of the Account Holder.
salutationOptional. Salutation using which the Account Holder is addressed. Example: Mr., Mrs., Ms.
firstName, middleName, lastNameOptional. Account Holder’s first, middle and last name.
profilePicURLOptional. Link to Account Holder’s profile image.
genderOptional. Account Holder’s gender.
mothersMaidenNameOptional. Account Holder’s mother’s maiden name.
dobAccount Holder’s date of birth details.
yearOptional. Year of birth in YYYY format.
monthRequired. Month of birth in MM format. Value must be between 1 and 12
dayRequired. Day of birth in DD format. Value cannot be more than the number of days in the specified month. For example, if the month of birth is June, day must be 30 or less.
VectorsAccount Holder’sVector details.
typeOptional. Type of Vector.
Allowed values: p for phone number; e for email.
valueOptional. Value based on Vector type specified. For example, if vectorType is p, specify Account Holder’s phone number; if vectorType is e, specify email ID.
isVerifiedOptional. Specify whether the Vector is verified or not. Allowed values: true, false. If the parameter is omitted or any other value is specified, it is set to false.
kycDetailsAccount Holder’s KYC details.
authTypeOptional. Type of document submitted for KYC. Allowed values: AADHAR, PAN, PASSPORT, VOTER_ID, DRIVING_LICENSE.
authDataRequired. Details based on the KYC type specified in authType. For example, if PAN is specified, provide the ten-character PAN identifier.
expiryTimeOptional. Expiry time of KYC in the ISO 8601 format YYYY-MM-DD'T'HH:MM:SS:sss'Z'
kycAttributesOptional. Additional information related to KYC.
kycStatusOptional. KYC status of the Account Holder. Supported values:MINIMAL, AADHAR_OTP,
kycStatusPostExpiryOptional. Status of KYC post expiry.
UpdateTimeOptional. ISO 8601 Format YYYY-MM-DD'T'HH:MM:SS:sss'Z'
customFieldsOptional. Any additional information you want to capture. Example: alternate phone number, UCIC.
popsOptional. Account Holder’s address details.
tagsOptional. A mechanism for classifying and filtering objects in Fusion.
cURL Sample
Switch Theme
Expand More
Copy
curl --location --request POST '{{fusion_base_url}}/api/v1/ifi/{{ifiID}}/applications/newIndividual' \
--header 'Content-Type: application/json' \
--header 'X-Zeta-AuthToken: {{token}} \
--header 'Cache-Control: no-cache' \
--data-raw '{
    "ifiID": "140793",
    "formID": "testapplication123468887",
    "spoolID": "123",
    "individualType": "REAL",
    "salutation": "Mr.",
    "firstName": "Komal",
    "middleName": "",
    "lastName": "Gitika",
    "profilePicURL": "",
    "dob": {
        "year": 1992,
        "month": 7,
        "day": 5
    },
    "gender": "FEMALE",
    "mothersMaidenName": "Rashmi",
    "kycDetails": {
        "kycStatus": "MINIMAL",
        "kycStatusPostExpiry": "string",
        "kycAttributes": {},
        "authData": {
            "PAN": "GRUR08890L"
        },
        "authType": "PAN"
    },
    "vectors": [
        {
            "type": "p",
            "value": "+919123456783",
            "isVerified": false
        }
    ],
    "pops": [],
    "customFields": {
        "companyID": [
            1,
            2,
            3
        ]
    },
    "tags": [
        {
            "type": "vbo",
            "value": "swiggy",
            "isVerified": false
        }
    ],
    "source": "postman"
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
  {
    "applicationID": "3791050",
    "formID": "testapplication123468887",
    "ifiID": 140793,
    "spoolID": "123",
    "status": "APPROVED",
    "individualID": "9be6a3ad-a6f1-494a-bb2a-d488c5bac1f2",
    "applicationType": "REAL",
    "salutation": "Mr.",
    "firstName": "Komal",
    "middleName": "",
    "lastName": "Gitika",
    "profilePicURL": "",
    "dob": {
        "year": 1992,
        "month": 7,
        "day": 5
    },
    "gender": "FEMALE",
    "mothersMaidenName": "Rashmi",
    "vectors": {
        "1e34d4d7-58c5-4f50-844b-38a28072ab16": {
            "type": "pan",
            "value": "GRUR08890L",
            "isVerified": false,
            "tags": [
                {
                    "type": "vbo-id",
                    "value": "258cdc62-93cf-46de-8f22-a78f69065ca7"
                }
            ]
        },
        "cc1d9534-84de-4aa3-bcd4-6d8318d5b608": {
            "type": "p",
            "value": "+919123456783",
            "isVerified": false,
            "tags": [
                {
                    "type": "vbo-id",
                    "value": "258cdc62-93cf-46de-8f22-a78f69065ca7"
                }
            ]
        }
    },
    "pops": {},
    "tags": {
        "e859e1f9-615e-4070-9352-78cadb1fe762": {
            "type": "vbo-id",
            "value": "258cdc62-93cf-46de-8f22-a78f69065ca7"
        }
    },
    "kycDetails": {
        "kycStatus": "MINIMAL",
        "updateTime": "Mar 18, 2021 1:50:56 PM",
        "expiryTime": "Feb 23, 2120 1:50:56 PM",
        "kycStatusPostExpiry": "MINIMAL",
        "authType": "PAN",
        "authData": {
            "PAN": "GRUR08890L"
        },
        "kycAttributes": {
            "pan": "GRUR08890L",
            "kycType": "MINIMAL",
            "authType": "PAN"
        }
    },
    "customFields": {
        "companyID": [
            1.0,
            2.0,
            3.0
        ]
    },
    "createdAt": "Mar 18, 2021 1:50:56 PM",
    "updatedAt": "Mar 18, 2021 1:50:56 PM",
    "source": "Fusion",
    "statusDetails": {},
    "dedupeDetails": {
        "updated": false,
        "accountHolderExists": true
    },
    "headers": {}
}
Code Copied

Case 1: Doesn’t exist, i.e. new application

If an account holder doesn’t already exist with the IFI, the account holder will be created after IFI’s review. Fintechs can subscribe to webhooks ( Fusion Events) to be notified when the application is updated

Case 2: Already exists

  • The /accountHolders/{accountHolderID} is then invoked by the fintech to request account holder details.

  • The response payload hence received will contain the KYC status (kycStatus) of the account holder. Below are the KYC statuses:

    • Full: Complete KYC of the account holder is done, i.e. the Aadhar XML, Aadhaar OTP or Aadhaar biometric KYC have already been completed
    • Minimal: Phone number and OVD details of the account holder have been verified
    • Shortfall: The KYC status of the account holder is incomplete, i.e. either the phone number, OVD details or both have not been verified yet.

The Fintech need not re-verify the KYC if:

  • The KYC status is already ‘Full’
  • The Account Holder’s existing KYC status is the same as that of the KYC requirement of the fintech. For example, if the required KYCstatus is ‘minimal’ as was required by the Fintech, then they need not re-do the KYC.

Update KYC Status from ‘Shortfall’ to ‘Minimal’

Fintech will invoke accountHolders/{{account_holder_id}}/createApplication to request an update of KYC status from ‘shortfall’ to ‘minimal’ by passing respective KYC details- contact number and OVD details, in request body. This creates an ‘update Account Holder’ application internally in the Fusion system. This application will then go through the defined approval workflow by the issuer. Once Account Holder’s KYC status is updated successfully, Fintech can issue products to it.

POST/api/v2/ifi/{{ifiID}}/accountHolders/{{account_holder_id}}/createApplication

Input Parameters

ParametersDescription
X-Zeta-AuthTokenIt should be same as the VBO token
ifiIDIt represents a unique identifier assigned to the IFI (Example: 140793)
Auth_TokenRespective Auth Token
requestIdRequest ID has to be unique per request
accountHolderIdThe Account Holder for which the KYC has to be updated
operationTypeKYC_SHORTFALL_TO_MIN

(This value will remain constant for Shortfall to Minimum KYC update)

kycStatusMINIMAL

(The value has to be "MINIMAL" only in the request body)

kycStatusPostExpiryMINIMAL

(The value has to be "MINIMAL" only in the request body)

authTypeThe authentication type on which the user is onboarded
authdataDetails of the "authType"
cURL Sample
Switch Theme
Expand More
Copy
curl --location --request POST 'https://fusion.preprod.zeta.in/api/v2/ifi/{{ifiID}}/accountHolders/{{account_holder_id}}/createApplication' \
--header 'X-Zeta-AuthToken: {{a}}' \
--header 'Content-Type: application/json' \
--header 'Cookie: AWSALB=dh7EbNqWqkugWqKeUbVQB0/o72Vf8zsTC3VQC/R8YrqKAqzzi1cySVnmZ2ytG5bG4j5SoKpzzjHWjQ1VLTD5mshAr25h+df0dSTeFi+dASJ1ngehHhRC8XNs1wdv; AWSALBCORS=dh7EbNqWqkugWqKeUbVQB0/o72Vf8zsTC3VQC/R8YrqKAqzzi1cySVnmZ2ytG5bG4j5SoKpzzjHWjQ1VLTD5mshAr25h+df0dSTeFi+dASJ1ngehHhRC8XNs1wdv' \
--data-raw '{
 "requestId": "request_kyc_19110102",
 "operationType": "KYC_SHORTFALL_TO_MIN" ,
 "reqPayload": {
   "kycStatus": "MINIMAL",
   "kycStatusPostExpiry": "MINIMAL",
   "authType": "PAN",
   "authdata": {
     "pan": "FYUBH9654N"
   }
 }
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
    "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
    "ifiId": 140793,
    "status": "ENRICHMENT_INITIATED",
    "sections": {
        "KycDetails": {
            "sectionId": "79ba3104-d103-451f-9e53-8b354fe5be93",
            "ifiId": 140793,
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "name": "KycDetails",
            "type": "KYC",
            "details": {
                "kycPayload": {
                    "ifiId": "140793",
                    "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
                    "authType": "PAN",
                    "authdata": {
                        "pan": "FFGPK9954E"
                    },
                    "kycStatus": "MINIMAL",
                    "accountHolderId": "eed858de-e7c9-4db4-a48d-58ecd8aea65a",
                    "kycStatusPostExpiry": "MINIMAL"
                }
            },
            "createdAt": "2020-11-18T23:01:26.914+05:30",
            "updatedAt": "2020-11-18T23:01:26.914+05:30"
        }
    },
    "vectors": [],
    "stages": [
        {
            "stageId": "43f85181-be16-498c-a1cf-ebbb90c7babc",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "DATA_CAPTURE",
            "status": "COMPLETED",
            "details": {},
            "result": {
                "validationPassed": {
                    "validation": "successful"
                }
            },
            "createdAt": "2020-11-18T23:01:27.479+05:30",
            "updatedAt": "2020-11-18T23:01:36.830+05:30"
        },
        {
            "stageId": "f55678da-7312-41d1-add9-209a985a4445",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "ASSESSMENT",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2020-11-18T23:01:27.851+05:30",
            "updatedAt": "2020-11-18T23:01:27.851+05:30"
        },
        {
            "stageId": "7d25b3c6-b4b4-4269-99a6-c6e6984c5d93",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "PROVISIONING",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2020-11-18T23:01:27.851+05:30",
            "updatedAt": "2020-11-18T23:01:27.851+05:30"
        },
        {
            "stageId": "30d1110c-668f-44f5-9b81-046f3bb85bb0",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "REVIEW",
            "status": "NOT_INITIATED",
            "details": {},
            "result": {},
            "createdAt": "2020-11-18T23:01:27.855+05:30",
            "updatedAt": "2020-11-18T23:01:27.855+05:30"
        },
        {
            "stageId": "21e6d195-a7d0-4473-9379-60aa87a4916a",
            "ifiId": 140793,
            "applicationId": "f0146a03-7cd2-4997-a305-398b5f0a09d6",
            "spoolId": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "name": "ENRICHMENT",
            "status": "INITIATED",
            "details": {},
            "result": {
                "validationPassed": {
                    "validation": "successful"
                }
            },
            "createdAt": "2020-11-18T23:01:27.871+05:30",
            "updatedAt": "2020-11-18T23:01:38.883+05:30"
        }
    ],
    "tags": [
        {
            "type": "spool-id",
            "value": "78ce2941-34b9-4233-95f6-17b0acd07443",
            "attributes": {}
        }
    ],
    "createdAt": "2020-11-18T23:01:25.555+05:30",
    "updatedAt": "2020-11-18T23:01:37.418+05:30"
}
Code Copied

Update KYC Status to Full KYC

The Full KYC is facilitated as per the respective IFI’s preference. For example, the RBL bank enables full KYC via Aadhaar XML KYC and Aadhaar Biometric KYC while IDFC Bank supports Aadhaar OTP KYC. The fintechs shall subscribe to any of the KYC methods provided by their IFIs to be able to get the Full KYC done for their users.

Application Status

After the application is successfully created, it is submitted to the Issuer for review. Based on the details submitted and the qualifying criteria set, the issuer approves or rejects the application. If the application is rejected, fintechs are suggested to address the reason and re-submit the application..

Fintechs shall configure the webhooks for the same to be notified of the update on the application. For more information on webhook events, please refer to Fusion Events

Keep track of this space for more updates