• Prepaid

    In locale

  • Prepaid

    In locale

Create Account Holder

Create Account Holder
Published on 20th August, 2021

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.

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.

Required Applicant Information

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

  • Personal information, like:
    • Full Name
    • Contact Information: Phone number, Email ID
    • Date of Birth
  • Officially Valid Document (OVD) details, like Aadhaar number, PAN card, Voter’s ID card, etc.
  • PEP, FACTA, OFAC declarations. (Refer Customer Verification- KYC, AML, and CFT guidelines for more information)

Depending on the program arrangement with the Issuer, the required applicant details are subject to change.

If you need to collect additional information, you can utilise custom attributes as described in the following sections. For example, you can store an Account Holder’s additional mobile number or Unique Customer Identification Code (UCIC) against the application.

Creating Application

In order to create a new account holder, an Application shall be created first.

The issuer will, then, review this 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.

Below endpoint is used to create an Application:

POST/api/v1/ifi/{{ifiID}}/spool/{{spoolid}}/application

Parameters

Parameter Description
IFI ID Unique ID of the IFI or the Issuer with which the fintech is running the program
Spool Unique ID of the workflow defined with the issuer that determines:
- Details needed as a part of application, such as PAN card number
- Workflow for processing the application
- Details of relationship formed between the IFI, fintech and account holder, once the application is approved
requestID Unique ID/UUID of the request
vectors Here, ‘Vector’ entails the unique contact details of the applicant
vector: type Type of the contact detail being captured. Allowed values:
- p: phone number
- e: email ID
vector: value Value of the contact details being captured
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": "Riya"
        }
    }
    }
}'
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": "Riya"
            },
            "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

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

Parameters Description
X-Zeta-AuthToken It should be same as the VBO token
ifiID It represents a unique identifier assigned to the IFI (Example: 140793)
Auth_Token Respective Auth Token
requestId Request ID has to be unique per request
accountHolderId The Account Holder for which the KYC has to be updated
operationType KYC_SHORTFALL_TO_MIN

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

kycStatus MINIMAL

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

kycStatusPostExpiry MINIMAL

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

authType The authentication type on which the user is onboarded
authdata Details 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