Step 1 - Install and Configure

smallcase Gateway Android SDK is available as a private gradle dependency. To install the Android SDK, add it to your app level build.gradle file.

// Include maven repository url and authentication details
repositories {
  
  // Starting from version 3.10.0 all versions of the sdk are now hosted on a public repository
  maven {
        url "https://artifactory.smallcase.com/artifactory/SCGateway"
    }
  
  // Only for versions < 3.10.0
    maven {
        url "https://artifactory.smallcase.com/artifactory/gradle-dev-local"
        credentials {
            username "${artifactory_user}"
            password "${artifactory_password}"
        }
    }
}

// Add smallcase Gateway SDK as a dependency
dependencies {
    implementation 'com.smallcase.gateway:sdk:$version'
}

• Replace $version with the latest version available.
  Eg - Current version is 3.2.0
• Replace "${artifactory_user}" and "${artifactory_password}" with user name and password which is given to all integration partners.

Configuration should happen as early as possible in your application's lifecycle. Configure smallcase Gateway Android SDK via AndroidManifest.xml :

<activity android:name="com.smallcase.gateway.screens.transaction.activity.TransactionProcessActivity"
  android:exported="true">          
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    	<category android:name="android.intent.category.BROWSABLE" />
    	<category android:name="android.intent.category.DEFAULT" />
    			<data
                android:host="{YOUR_GATEWAY_NAME}"
                android:scheme="scgateway" />
  </intent-filter>
</activity>

<activity android:name="com.smallcase.gateway.screens.common.RedirectActivity"
          android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />

                <category android:name="android.intent.category.BROWSABLE" />
                <category android:name="android.intent.category.DEFAULT" />

                <data
                    android:host="{YOUR_GATEWAY_NAME}"
                    android:scheme="scgatewayredirect"
                    />
            </intent-filter>
</activity>

Replace "{YOUR_HOST_NAME}" with unique host name which is given to every integration partners.

🚧

Note

If your app targets Android 12 or higher you must explicitly declare the android:exported attribute for these activities. If an activity doesn't have an explicitly-declared value for android:exported, your app can't be installed on a device that runs Android 12 or higher.

Step 2- Environment Setup

To start using gateway setup the gateway with the desired configuration by calling setConfigEnvironment method which is available as a static method of SmallcaseGatewaySdk class.

SmallcaseGatewaySdk.setConfigEnvironment(environment,object : SmallcaseGatewayListeners {
  override fun onGatewaySetupSuccessfull() {
    //Initialise user
  }

  override fun onGatewaySetupFailed(error: String) {
    //Retry 
  }
})

SmallcaseGatewaySdk.INSTANCE.setConfigEnvironment(environment,
                                                  new SmallcaseGatewayListeners()
{
  @Override
  public void onGatewaySetupSuccessfull() {
    //Initialise user
  }
  
  @Override
  public void onGatewaySetupFailed(String error) {
     //Retry 
  }   
});

To setup, create a config object conforming to Environment object. Configuration defines the settings to be used by the gateway.

class Environment(
    val buildType: Environment.PROTOCOL,
    val gateway: String,
    val isLeprachaunActive: Boolean,
  	val isAmoEnabled: Boolean,
    val preProvidedBrokers: List<String>
) {
    enum class PROTOCOL {
        PRODUCTION
    }
}

Params :

1. buildType (required): This defines the Url environment to which all the gateway apis would point to Possible values - Environment.PROTOCOL.PRODUCTION
2. gateway (required): This is a unique name given to every gateway consumer
   Eg : moneycontrol
3. isLeprachaunActive (required): For Testing purpose only. Default value is false
4. isAmoEnabled (required): To control after-market order placement.
5. preProvidedBrokers (required): If you want to support only certain brokers, default all brokers are shown if empty list is passed
   Possible values - aliceblue, angelbroking, axis, dhan, edelweiss, fisdom, fivepaisa, fundzbazar, groww, hdfc, icici, iifl, kite, kotak, motilal, trustline & upstox

📘

Note

Call setConfigEnvironment every time there is any change in the setup.
setConfigEnvironment must be the first method to be fired.If setup is not called all other methods will not work.
Initialise the SDK onGatewaySetupSuccessfull callback.
Retry setConfigEnvironment onGatewaySetupFailed.

Step 3- Initialise user session

User initialization starts a session between the distributor and the gateway. Whenever there is a change in user session, this method needs to be triggered.

SmallcaseGatewaySdk.init(InitRequest("<Insert SDK Token>"),
                                        object :DataListener<InitialisationResponse> {
    override fun onSuccess(authData: InitialisationResponse) {
      
    }
                                          
    override fun onFailure(errorCode: Int, errorMessage: String) {
    }
})

SmallcaseGatewaySdk.INSTANCE.init(new InitRequest("YOUR SMALLCASE AUTH TOKEN"),
                                  new DataListener<InitialisationResponse>() {
     @Override
     public void onSuccess(InitialisationResponse response) {
       
     }
  
  	 @Override
     public void onFailure(int errorCode, String errorMessage) {
       
     }
});

Params :

1. sdkToken (required): JWT with the information of user signed using a shared secret between smallcase API and gateway backend. Learn more about using JWT
2. gatewayInitialisationListener (required): After onSuccess any transaction can be triggered.
   After onFailure sdk should be reinitialised.

Step 4- 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 app).

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

Create transactionId API reference -

• Single stock (basket) orders
• smallcase orders or SIP setup
• Holdings import
• Broker connect

ii - Call triggerTransaction SDK method

To start the actual transactional flow, call the triggerTransaction method which is available as a static method of SmallcaseGatewaySdk class.

SmallcaseGatewaySdk.triggerTransaction(activity
                                       ,transactionId,
                                       object : TransactionResponseListener {
  override fun onSuccess(transactionResult: TransactionResult) {
      // Transaction successful
  }
  
	override fun onError(errorCode: Int, errorMessage: String) {
      // Transaction failure
  }
})

SmallcaseGatewaySdk.INSTANCE.triggerTransaction(this,
                                                transactionId,
                                                new TransactionResponseListener()
{
            @Override
            public void onSuccess(TransactionResult transactionResult) { 
              // Transaction successful
            }
 
            @Override
            public void onError(int errorCode, String errorMessage) {
              // Transaction failure
            }
});

Params :

1. activity (required): Current activity reference.
2. transactionId (required): a unique string that you received from backend in the previous step

B. For Non-transactional flows

i - Call relevant SDK method

(More details in Non-transactional flow section)

Step 4 - Save order response

Order response is shared in the onSucess() block of the triggerTransaction method as well as over API webhooks
Check response structure here

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

A list of transaction errors is available here

Non-transactional flows

📘

Note:

In order to use any of the following methods, the gateway session should be initialized with relevant user data.

Broker Account Opening

To trigger account opening flow call triggerLeadGen method which is available as a static method of SmallcaseGatewaySdk class.

SmallcaseGatewaySdk.triggerLeadGen(requireActivity(), params)

SmallcaseGatewaySdk.INSTANCE.triggerLeadGen(requireActivity(), params);

Params

1. activity (required): Current activity reference.

2. params: (optional): pass user information in a hashmap or null if no user information is passed.

• params 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 params object are optional.

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

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.

📘

Note

This flow is only available for connected users.

SmallcaseGatewaySdk.logoutUser(activity = requireActivity(), object: SmallcaseLogoutListener {
		override fun onLogoutSuccessfull() {
      // User logged out successfully
    }

    override fun onLogoutFailed(errorCode: Int, error: String) {
      // User logout failure
    }
})

Params :

1. activity (required): Current activity reference.

Show Orders

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

SmallcaseGatewaySdk.showOrders(
  activity = requireActivity(),
  brokers = null,
  showOrdersResponseListener = object : DataListener<Any> {
  override fun onSuccess(response: Any) {
    /**
    * Returns true once user closes the Order List page successfully.
    */
  }
  
  override fun onFailure(errorCode: Int, errorMessage: String) {
    /**
    * Gateway flow ended before viewing the Order List page
    * https://developers.gateway.smallcase.com/docs/transaction-errors#show-orders-error
    */
  }
})

SmallcaseGatewaySdk.INSTANCE.showOrders(
  this.requireActivity(), 
  null, 
  new DataListener() {
    public void onSuccess(@NotNull Object response) {
      /**
      * Returns true once user closes the Order List page successfully.
      */
    }
    
    public void onFailure(int errorCode, @NotNull String errorMessage) {
      /**
      * Gateway flow ended before viewing the Order List page
      * https://developers.gateway.smallcase.com/docs/transaction-errors#show-orders-error
      */
    }
  })

Params :

1. activity (required): Current activity reference.
2. brokers (optional): list 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)