Enable seamless investment experience in buying and selling of securities (stocks, ETFs, InvITs & REITs), natively in your apps and website.

Supports:

single stock order: place order for single security 1️⃣
basket order: place order for multiple security (can be a mix of buy and sell) in one go 🧺

Also known as: single stock order / basket order / SST

How it works

Good to know

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

Sequence diagram

Integration details

Step 1: Create a transaction on your server-side

When a user intends to transact, a transactionId has to be created for the SDK interaction.
Hit the create stocks order transaction API from your server to get a unique transactionId by specifying order config.

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 stock order transactionId (generated in step 1) to SDK's trigger transaction method. Gateway SDK will now show relevant screens (broker chooser, broker login, order confirmation, status, etc) to the user.

Step 3: Handle response on client- or server- side

Once the trigger transaction method resolves successfully, you can use any of these approaches to fetch order details -

3.1 From SDK Response (client-side)

Trigger transaction will respond with

connected user auth token
You can decode the JWT and get smallcaseAuthId of the linked broker account (on your server).
order details
This object states the status of the order and execution details (order type, avg. buy/sell price, quantity filled, etc) for each security.

3.2 Using webhook/postback (server-side)

Optionally, you can register a stocks order webhook for your gateway.
Once done, every time a user places an order on the client-side and [if at all] there's an update on open order (AMO, limit order), smallcase Gateway will hit your registered webhook with the user's order details, transactionId, smallcaseAuthId. The data can then be saved against the relevant users in your systems on every webhook hit.

In webhook hits, how can we identify the user for every order update received?

If you save transactionId(s) against each user account, you can use transactionId passed in webhook to determine the related user.

Alternatively, the create transaction API supports the notes mechanism. You can pass your unique user identifier as notes while creating transactionId, and you will further receive the same in webhook response, SDK response and orders API.

3.3 Using Gateway API (server-side)

Use Stocks order details API to fetch details about the order. This API will respond with order details.

Use Fetch transaction details API to get details about the transaction (status, any error returned on SDK itself). This API should be used to fetch & link smallcaseAuthId against the user account in your database.

Try order placement

Try it live

Response structure

Order details for securities orders can be consumed in three ways

SDK response
- where: client-side
- when: user closes the Gateway SDK flow
- structure: described below
Webhook hits
- where: server-side (push mechanism)
- when: every time any user places an order, and when there is any update for open order
- structure: described below (the batch object, orderBatches[0], is shared)
- remark: most pragmatic way to listen for order execution updates in real-time
API response
- where: server-side (pull mechanism)
- when: on need basis
- structure: described below (the batch object, orderBatches[0], is shared)

response structure, explained

transactionId: [string] transaction identifier created from your server and passed to SDK

smallcaseAuthToken: [string] connected user auth token (contains smallcaseAuthId in payload)

broker: [string] broker key representing broker with which user transacted (eg: groww)

notes: [string] you can pass up to 256 characters in create transaction API for order tagging

`orderBatches` array

[array of single batch object] a batch represents one or more securities that the user confirmed to transact

batchId: [string] unique ID for this batch of orders

variety: [string] type of order: regular for normal order, and amo for aftermarket order

quantity: [integer] count of securities part of this batch

filled: [integer] count of securities which got successfully executed

buyAmount: [decimal] total amount invested using this batch order to buy securities

sellAmount: [decimal] total amount gained using this batch order to buy securities

completedDate: [string] UTC timestamp when this batch finished its lifecycle

status: [string] batch-level order status. It is recommended to use orders[].status & unplaced[].status instead of this

batch-level status (enums)

Note: for securities orders, we recommend using individual stock level status key (orders[].status & unplaced[].status) instead of this batch-level status.

`orders` array

[array of order object(s)] each order represents a security that was placed with broker

tradingsymbol: [string] NSE ticker/symbol of the security

transactionType: [string] BUY or SELL

orderType: [string] MARKET or LIMIT

status: [string] defines current status of the stock order (aka stock level status)

stock-level status (enums)

Transitionary status:
PLACED the order placed with broker
ERROR the order execution status is unknown. Contact gateway support to reconcile the order from the user's tradebook manually.

Final status:
COMPLETE the order executed successfully on the exchange
PARTIAL only partial quantity in the order got filled (orders[].filledQuantity < orders[].quantity)
REJECTED the order was placed but rejected by the broker/exchange. A possible reason could be insufficient funds
CANCELLED the order was placed but cancelled by the broker/exchange. A possible reason could be low liquidity
CANCELLED AMO the order was placed as an AMO but was cancelled by the user before execution

quantity: [integer] number of shares to trade

filledQuantity: [integer] number of shares traded on the exchange

averagePrice: [decimal] average price at which the order was executed (only for COMPLETE orders)

product: [string] CNC

exchange: [string] NSE

exchangeOrderId: [string] exchange generated order ID. orders that don't reach the exchange will not have ID

errorCode: [string] Represents the reason for the failure of an order. Set of possible codes mentioned in Order errors: placement and execution guide

statusMessage: [string] Textual description of the order's status. While it is a human-readable explanation at times, it can be gibberish at other times. We recommend not showing it to the user, and rather having it on your backend for support functions.

`unplaced` array

[array of unplaced order object] each order represents a security that couldn't be placed with the broker due to some error

The object structure remains same as the orders array above.

unplaced[].status = ERROR always.

broker: [string] broker key representing broker with which user transacted (eg: groww)

transactionId: [string] transaction identifier created from your server and passed to SDK

notes: [string] you can pass up to 256 characters in create transaction API for order tagging

/* below keys are shared in webhook requests */

checksum: [string] used for webhook authentication; more details in webhooks guide

timestamp: [string] UTC timestamp at which the checksum was generated

smallcaseAuthId: [string] smallcaseAuthId

Notes

broker support: all smallcase integrated brokers (keys: aliceblue, angelbroking, axis, dhan, edelweiss, fisdom, fivepaisa, fundzbazar, groww, hdfc, icici, iifl, kite, kotak, motilal, trustline & upstox)
For securities transaction, we strongly recommend using stock-level status (orders[].status and unplaced[].status) over batch-level status
limit orders: users (5Paisa, Groww & Zerodha) can now place limit orders (Limit, SL, SLM). More here
ticker support: Valid NSE ticker for securities listed on NSE

FAQs

1. What is guest user flow vs connected user flow?

Consider guest user flow as a first-time user experience (FTUX):
When a user interacts with smallcase Gateway for the first time, you will not know their broker details (recall: smallcaseAuthId).

Hence you will -

initialise gateway session in SDK with guest user auth token
trigger transaction with transactionId created in step 1

Now, SDK will ask users to choose their broker account from the set of available brokers.

On successful transaction completion, SDK shares connected user auth token in response.
You can save the smallcaseAuthId from the JWT, and use it in returning the user journey.

Connected user flow is for returning user experience (RTUX):
When the same user wants to interact with the gateway again, you can now initialise the gateway session with a connected user JWT.

This time, SDK will simply continue with the linked broker account. The user must login with the linked broker account to continue the transaction. This ensures that the same account is used for transactions, and investments are made on top of previous ones; from the same broker account.

Can we use guest user flow for FTUX & RTUX?
Yes, that's possible. SDK does not restrict the usage of guest flow in returning user journeys.

2. What is implementation difference for single stock and basket order?

one / more securities has to be passed in order config while creating transaction (discussed below)
one / more securities will be available in the transaction response

3. Can we have any UI customization for basket order?

Yes, we have support to configure name and logo of the basket created at your end.

You can pass these details in the create transaction API. Learn here

Custom basket name ("Smart Basket") and logo (the food basket image)