Prerequisites

For integrating Gateway SDK & API, there is a set of integration keys required.

1. How do we get these integration keys?

If you are a developer, check with your product/business team whether they have already received integration keys.

If you work in the product/business team and are already in touch with Gateway's business team, they would have asked you to fill out an onboarding form with basic questions about your integration. Once filled, the team will share the set of keys based on the form inputs.

2. We are getting CORS error while using JS SDK. How to resolve?

The JS SDK requires whitelisting of any frontend domain (including localhost) on which SDK has to run. This can be done by simply communicating domains & localhost ports over email. We typically whitelist in an hour on a working day.

Notes:

1. all subdomains can be whitelisted using regex (eg. https://*.your-website.com)

2. your API domains does NOT need to be whitelisted

Transactional flow

A transaction has to be created from your server every time your user wants to place an order, import holdings or connect a broker account.

The transaction is represented by a unique transactionId which has a lifespan of 5 minutes from the time of creation.

Transaction handling

1. on server:
   1. use Create Transaction API for relevant feature integration
2. on SDK:
   1. initialise gateway session on SDK
   2. trigger transaction by passing transaction id on SDK
   3. handle transaction response / error
3. on server:
   1. fetch order details (or holdings) using relevant order details (or fetch holdings) API / webhook

Broker identification

Gateway uses JSON Web Tokens (JWT) for broker identification & linking.

As many of us are known by nicknames, Gateway's usage of JWTs is no different. 💁 Auth token, smallcase auth token and gateway auth token mean the same thing - JWT used by Gateway to recognise user's broker account.

smallcaseAuthToken: It is a JWT containing broker account identification payload, and signed with the shared secret. It can be created for guest as well as connected users.

Types of auth token

1. Guest user auth token

   Gateway provides a guest user experience by prompting users to select their broker from the available brokers.

   Sample JWT Payload:

   Guest JWT Payload

   {
     "guest": true,
     "exp": 2556124199
   }
   

   Sample auth token (signed with secret "have-a-good-day"):

   Guest JWT (with algo=HS256, signed with a secret)

   eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJndWVzdCI6dHJ1ZSwiZXhwIjoyNTU2MTI0MTk5fQ.PHmNnVVqhtB7sZjo5_VWlOs5p_HQzIr3qaS9CV0kiAo
   

2. Connected user auth token

   Gateway providers connected user experience by helping users navigate to their already linked broker account. This eliminates the need for users to select their broker after first-time login.

   Sample JWT Payload:

   Connected JWT Payload

   {
     "smallcaseAuthId": "5f0321b5f3743c31d95abd35",
     "exp": 2556124199
   }
   

   Sample auth token (signed with secret "have-a-good-day"):

   Connected JWT (with algo=HS256, signed with a secret)

   eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzbWFsbGNhc2VBdXRoSWQiOiI1ZjAzMjFiNWYzNzQzYzMxZDk1YWJkMzUiLCJleHAiOjI1NTYxMjQxOTl9.EC6B435Xsw02dDy_LCmHqKmEmJOqhq3f2MuSOjUmxYs
   

   Learn more about smallcaseAuthId and returning user journeys here.

1. What is `smallcaseAuthId` and how do we get it?

Check out this FAQ 👇

What is smallcaseAuthId?

2. What is difference between `smallcaseAuthId` vs `smallcaseAuthToken`?

• smallcaseAuthId: It is an unique identifier for broker account with which user has logged in.

• smallcaseAuthToken: It is a JWT containing broker account identification payload, and signed with the shared secret. It can be created for guest as well as connected users.

  • Connected auth token are JWTs with payload containing the key smallcaseAuthId

smallcaseAuthId can be stored against your user's account for retuning user experience (and other use cases like fetch holdings).

smallcaseAuthToken should be generated on the fly with short expiry set.

3. How to generate and verify JWT?

There are many libraries available across different backend languages. Check out the JWT's official library list.

For smallcase Gateway's use case of JWT, check our sample code snippets for JWT creation (in JS, Python, PHP, Java, C#).

4. Why should we always create and verify JWT on our server?

JWT creation (signing) and verification involve the usage of JWT Secret. Since a secret is involved, the same should NEVER be used on your front end. If used, anyone can access it by debugging the frontend code on the client-side.

5. We are using connected user auth token flow. What should we keep in mind?

Using a connected user auth token means that you have linked smallcaseAuthId to your user's account. Your backend API should have sufficient checks to generate and share connected auth tokens only for your authenticated user. That too for smallcaseAuthId linked to your logged-in user.

📘

Can we directly place trade from our server, on user's behalf?

No, you cannot place server-to-server order on behalf of your user.

Your user must always log in (if a session does not exist) with their broker via Gateway SDK flow whenever they want to transact.

smallcase auth token cannot be used to maintain/refresh the user's broker login session. Login session is handled by broker themselves, and Gateway does not facilitate maintaining such session on server-side.

Test accounts

Also known as Leprechaun mode, Virtual mode.

Using leprechaun mode, you can easily stimulate order placements and test out the end-to-end integration.

For each broker, we have a leprechaun mode (except for Dhan, Fisdom, Groww and Motilal Oswal). You can use any of the leprechaun brokers to test flows.

This helps in two ways:

1. avoids the need for using actual funds.
2. market orders can be placed even when the market is closed.
   • market timings are controlled internally by smallcase team

Check our guide on using virtual tokens (leprechauns) for testing.

1. How can we get leprechaun tokens?

We share leprechaun tokens along with the integration keys. If you did not receive/want more tokens, drop us an email in the existing email thread.

We also provide special tokens to stimulate conditions like low funds, order failure.

2. I am getting `market_closed` in "kite-leprechaun" account?

Market timing for leprechaun broker accounts is internally controlled by the smallcase team.

If you want to test the market open scenario, you can try using the same leprechaun token with multiple brokers. Generally, we keep markets open for at least some brokers.

However, if you want to test a certain scenario in a particular leprechaun broker, reach out to our integrations team and we will turn markets on/off per the request.

3. Should we test our flow end-to-end with each of the leprechaun brokers?

No, that's not required.