With smallcase Gateway, you can easily import the latest snapshot of a user’s stock, ETF and smallcase holdings, upon one-time user consent.

Using holdings data will help you build a holistic view of a user's equity investments.

How it works

Good to know

To continue, we recommend reading following sections of the Getting Started guide:

• Integration keys
• Overview of transactional flow
• JWT usage for broker account mapping

Sequence diagram

Integration details

Step 1: Create a transaction on your server

When a user intends to import holdings, a transactionId has to be created for the SDK interaction.
Use create holdings import transaction API on your server to create and fetch a unique transactionId.

Step 2: Integrate Gateway SDK on client-side

2.1 Initialise gateway session

Use a relevant guest / connected auth token to initialise the gateway session.

Learn more about initialising the gateway session in respective SDK integration page.

2.2 Pass transactionId to trigger transaction method

Next, pass the holdings import transactionId (generated in step 1) to SDK's trigger transaction method. Gateway SDK will now show relevant screens (broker chooser, broker login, import authorisation, etc) to the user. Once done, the user's latest holdings snapshot is saved in the smallcase system.

Step 3: Handle response on client or server

3.1 From SDK response (client-side)

Trigger transaction will respond with a connected user auth token.
You can decode the JWT and get smallcaseAuthId of the linked broker account.
More in the next step.

OR

3.2 Using webhook/postback (server-side)

Optionally, you can register a holdings import webhook for your gateway.
If done, every time a user import their holdings on the client-side, smallcase Gateway systems will hit your registered webhook with the user's holdings data, transactionId, smallcaseAuthId. The data should be saved against the relevant user in your systems on every webhook hit.

Step 4: Fetch holdings from your server

On getting success confirmation from the trigger transaction method, you can fetch relevant holdings of the user from your server.

If, not using webhook

Fetch holdings API should be called from your server by passing relevant connected user auth token (recall: SDK shares this in step 3.1).

Else if, using webhook

Your server can simply pull holdings data (recall: this data was saved in the database at step 3.2).

Demo: Try holdings import

Response Structure

Holdings data can be consumed in two ways:

1. Fetch holdings API
   This API requires connected user auth token which can be consumed from SDK's transaction success response or fetch transaction details
2. Holdings import webhook/postback

Holdings v2 response structure and response is available in Holdings Import v2 📃 guide

Notes

• broker support: 5Paisa, Angel Broking, Dhan, Fidsom, Groww, IIFL, Motilal Oswal, Trustline, Upstox & Zerodha

• session-based holdings refresh: Most brokers (all except Zerodha) require client-side broker login to update the holdings data (i.e. latest snapshot). Hence, a HOLDINGS_IMPORT transaction has to be triggered via SDK to refresh the user's holdings, each time user places an order directly from their broker's terminal.

• Long-lived session: For supported brokers (Zerodha) long lived session, fetch user holdings API can be used to refresh the holdings snapshot (without doing broker login again). The user will still have to authorise holdings for the first time.

  • Since the session is long lived (and not perpetual), snapshotDate field should be taken into consideration while directly fetching holdings via API. Snapshot date basically denotes timestamp when the latest snapshot for holdings was captured from the broker.
  • Snapshot date should be compared with the timestamp when the fetch user holdings API was called. If not latest, then the session with the broker needs to be refreshed (in the form of broker login). User completing a holdings import transaction again will ensure session is refreshed.