Integration Guides
Try Demo

Broker Account Opening

Offer seamless demat account opening experience to your users

Suggest Edits
400
1332

Users can open an account with a broker of their choice: 5Paisa, HDFC Sec, Kotak, Upstox & Zerodha.

To trigger the Account opening flow, trigger the relevant signup method of Gateway SDK.

Steps

1. Triggering SDK method

Learn more about signup method in respective SDK doc:

2. Save lead ID from SDK response

On close of Gateway's account opening flow (aka leadgen flow), the SDK will return the following data —

{
    "leadId": null,
    "status": "[INITIALIZED/DETAILS_REGISTER/BROKER_REGISTER]"
}

{
    "leadId": "612e1fc94d261b4aed130cb8",
    "status": "[SUBMITTED/COMPLETED]"
}

{
    "leadId": "612e1fc94d261b4aed130cb8",
    "status": "Account opened"
}

Status description

StatusDescription
INITIALIZEDUser dropped off before entering phone number
VERIFICATIONUser dropped off before verifying mobile OTP
DETAILS_REGISTERUser dropped off right after verifying mobile OTP
(but before filling more details - name & email)
BROKER_REGISTERUser dropped off after entering personal details
(but before choosing a broker)
LEAD SELECTED BROKERUser has selected its preferred broker, but hasn't provided its personal details
LEAD PENDING BROKER SUBMISSIONUser has provided all the details to us and we are currently waiting for broker's response on the lead
SUBMITTED / PROCESSINGUser successfully submitted the lead. Account opening is in process
Account openedlead successfully opened a demat account

The leadId is shared if a user submits the broker of their choice (gateway flow complete). The same can be saved in your database for the related user.

3. Fetch details using Lead status API

To check for the lead's account opening status, use the following lead status gateway API -

curl --location --request GET 'https://gatewayapi.smallcase.com/v1/<YOUR_GATEWAYNAME>/engine/leadStatus?leadId=612e1fc94d261b4aed130cb8' \
--header 'x-gateway-secret: <YOUR_GATEWAY_API_SECRET>' \
--header 'x-gateway-authtoken: <GUEST_AUTH_TOKEN>'

Sample responses

{
    "success": true,
    "errors": null,
    "data": {
        "leadId": "61cf1d56092bd30ed468feb8",
        "leadCreationDate": "2021-12-31T15:10:14.608Z",
        "status": "Account opened",
        "accCreatedDate": "2021-12-20T18:00:00.000Z",
        "stage": "Completed",
        "leadJourneyStatus": "COMPLETED",
				"lastUpdatedAt": "2022-08-29T09:56:37.251Z",
        "leadAccepted": true
    }
}

{
    "success": true,
    "errors": null,
    "data": {
        "leadId": "61b339be29cc994a591a55bc",
        "leadCreationDate": "2021-12-10T11:27:58.613Z",
        "status": "PROCESSING",
        "stage": "E-SIGN VERIFIED",
        "leadJourneyStatus": "PROCESSING",
        "lastUpdatedAt": "2022-08-29T09:56:37.251Z",
        "leadAccepted": true
    }
}

{
    "success": true,
    "errors": null,
    "data": {
        "leadId": "623087e3849671cfba579b54",
        "leadCreationDate": "2022-03-15T12:34:43.607Z",
        "status": "PROCESSING",
        "stage": "Submitted",
        "lead_journey_status": "LEAD ACCEPTED BY BROKER",
        "lastUpdatedAt": "2022-08-29T09:56:37.251Z",
        "lead_accepted": true
    }
}

{
    "success": true,
    "errors": null,
    "data": {
        "leadId": "58ecb4847b081b6cf331a219",
        "leadCreationDate": "2020-11-02T08:27:26.357Z",
        "status": "PROCESSING",
        "leadJourneyStatus": "LEAD REJECTED BY BROKER",
        "lastUpdatedAt": "2022-08-29T09:56:37.251Z",
        "leadAccepted": false
    }
}

{
    "success": true,
    "errors": null,
    "data": {
        "leadJourneyStatus": "[ONLY MOBILE NO ENTERED/ONLY MOBILE VERIFIED/ONLY MOBILE VERIFIED]"
    }
}

{
    "success": true,
    "errors": null,
    "data": {
        "leadJourneyStatus": "LEAD DETAILS NOT AVAILABLE FOR YOU"
    }
}

{
    "success": true,
    "errors": null,
    "data": {
        "leadJourneyStatus": "LEAD DETAILS DOES NOT EXIST"
    }
}

📘

Notes

  1. The signup flow requires initialising a Gateway session (either guest or connected auth token) before calling the signup method.

  2. For "Account opened" status, accCreatedDate is not always available.

  3. For "PROCESSING" status, the stage key is not always available. We highly recommend against using the same since it is not in a standardised format.

  4. leadAccepted key can be of undefined value, which means that it is unclear from the broker side whether the lead is accepted or not, it will get updated later as per the response we get from the broker later.

👍

Try it out

https://www.smartinvesting.io/signup

FAQs

1. Is there webhook support for leads? No, we do not support webhook for lead updates at the moment.
2. Should we use API secret in the x-gateway-secret header? Yes, the share API secret has to be used for using any of the Gateway APIs.
3. Is there a way to hide certain brokers from account opening flow? We are working on this feature and will keep all integration partners posted on the same.

Updated over 2 years ago