JavaScript SDK

Step 1 - Installation

smallcase Gateway SDK supports loading its JavaScript SDK via a CDN. The SDK is compatible with all major browsers and JS libraries/frameworks

To include the SDK, include the following script at the bottom of the body tag —

<script src="https://gateway.smallcase.com/scdk/2.0.0/scdk.js" type="text/javascript" />

Step 2 - Initialise gateway session

Once the SDK loads, scDK class is available in JavaScript's global scope.

To initialise the gateway session, instantiate the scDK class. Example —

const gatewayInstance = new window.scDK({
  // ! Use valid gateway name here
  gateway: "<gateway_name>",
  /*
   * ! Use valid auth token
   * Details - https://developers.gateway.smallcase.com/docs/getting-started#broker-identification
   */
  smallcaseAuthToken: "<guest / connected user JWT>",
  config: {
    // Should allow after market orders?
    amo: true
  }
})

Possible object keys in the constructor parameter -

1. gateway (required): unique gateway name assigned for your integration
2. smallcaseAuthToken (required): JWT containing a unique user identifier signed with the gateway secret. Learn more about using JWT
3. config (optional, default: { amo: false }): configuration object that can contain a boolean key named amo to control after-market order placement

Note
scDK follows the singleton pattern where subsequent calls to scDK constructor will return the instance created in the first instantiation. If the instance needs to be re-initialized, use the init method available on the created instance. More details here

Step 3 - Triggering SDK method

A. For Transactional flows

Transactional flows are those user journeys where interaction with their broker is required to complete the flow. For example - placing stocks / smallcase order, importing user holdings, connecting broker account to your app.

smallcase Gateway assigns a unique transactionId for each such user intent. The transactionId is a short-lived identifier that represents a single user interaction session.

i - Create transactionId

The transactionId can be created by making a server-to-server request to Create transactionId API with relevant order config. The API call must be made from your backend (it is critical that secrets not be used on the frontend).

So whenever your user wants to perform transaction action, your frontend must call your backed with relevant order config, which in turn will hit smallcase Gateway's create transactionId API and respond back with transactionId.

Check create transactionId in API references

ii - Call triggerTransaction SDK method

To start the actual transactional flow, call the triggerTransaction method. It accepts a single parameter with two keys -

1. transactionId (required): a unique string that you received from backend in the previous step
2. brokers (optional, default: all brokers will be shown): array of broker keys that you want to display in broker chooser (supports: aliceblue, angelbroking, axis, dhan, edelweiss, fisdom, fivepaisa, fundzbazar, groww, hdfc, icici, iifl, kite, kotak, motilal, trustline & upstox)

Example —

gatewayInstance.triggerTransaction({
  // ! Use valid transactionId here
  transactionId: "<transactionId>"
})
.then(txnResponse => {
  /*
   * Gateway flow ended after order placement
   * Response structure & example - https://developers.gateway.smallcase.com/docs/transaction-response
   */
  console.log('received response:', txnResponse);
})
.catch(err => {
  /*
   * Gateway flow ended before order placement
   * Possible errors - https://developers.gateway.smallcase.com/docs/transaction-errors
   */
  console.log('received error:', err.message);
});

B. For Non-transactional flows

i - Call relevant SDK method

(More details in Non-transactional flow section)

Step 4 - Handle order response

Order response is shared in the .then block of the triggerTransaction promise as well as over API webhooks

Check response structure in Transaction Responses guide

In case the transaction is not placed with the broker, any error is available in the .catch block

A list of transaction errors is available in Transaction Errors guide

Non-transactional flows

Note: In order to use any of the following methods, scDK class must be instantiated (the gateway session should be initialized with relevant user data).

Broker Account Opening

Trigger the signup method to start the account opening signup flow.

It accepts an optional parameter -

• userDetails can have one or more of the following string keys containing user details:
  • name - Full name
  • email - Email address
  • contact - Contact number

The keys inside the userDetails object are optional.

And for all relevant keys passed to the signup method, the SDK will pre-populated relevant user data in the signup flow, ensuring a smooth user experience

Example usage

gatewayInstance.signup({
  name: 'Chuck Noris',
  email: '[email protected]',
  contact: '9876543210',
})
.then(
  () => {
    console.log("signup flow has now ended");
  }
);

Show Orders

This will display a list of all the orders that a user recently placed. This includes pending, successful, and failed orders.

Example usage

gatewayInstance.showOrders()
.then((res) => {
	console.log('Returns true once user closes the Order List page successfully', res);
})
.catch(err => {
	console.log('In case some error has occurred on the order list page', err.message);
})

Logout from smallcase platform

This method is particularly useful when your users want to switch accounts for the same broker. When triggered, this method will make sure that the user gets logged out from the smallcase platform. So that the next time user interacts with smallcase Gateway, they will be asked to log in again. Learn more about the flow.

gatewayInstance.brokerLogout();

Note: This flow is only available for connected mode (SDK has to be initialised with connected user auth token).