--- page_source: https://docs.juspay.io/upi-inapp/android/interaction-with-sdk/initiating-the-sdk page_title: Initiating the SDK --- ## Initiating the SDK To initialise the SDK, client needs to call the `initiate` SDK API. The initiate api call boots up the SDK and makes it ready for all other operations Follow the below steps to make an initiate SDK call: ### Step 1 Create an instance of HyperServices The SDK exposes the `HyperServices` class. Create an object of this class for all upcoming operations #### Code Snippets: - #### Java Code Snippet: ```java HyperServices hyperInstance = new HyperServices(fragmentActivity, viewgroup); ``` #### Kotlin Code Snippet: ```kotlin hyperServicesHolder = HyperServiceHolder(this) ``` ### Step 2 Create Initiate payload Initiate API takes two parameters as input. One of the parameter is a JSON object referred as `InitiatePayload`. This payload contains certain key value pairs used by the SDK to perform a successful initiate Refer to the following table for information about the description and sample payload. #### Code Snippets: - #### Java Code Snippet: ```java // This function creates intiate payload. private JSONObject createInitiatePayload() { JSONObject sdkPayload = new JSONObject(); JSONObject innerPayload = new JSONObject(); JSONObject signaturePayload = new JSONObject(); try { // generating inner payload innerPayload.put("action", "initiate"); innerPayload.put("merchantKeyId", ""); // Put your Merchant ID here innerPayload.put("clientId", "CLIENT_ID"); // Put your Client ID here innerPayload.put("environment", "production"); innerPayload.put("issuingPsp", "YES_BIZ"); innerPayload.put("signature", "...."); // Generated signature for signature payload innerPayload.put("signaturePayload", signaturePayload); // block:start:generatingRequestId sdkPayload.put("requestId", ""+ UUID.randomUUID()); // block:end:generatingRequestId sdkPayload.put("service", "in.juspay.hyperapi"); sdkPayload.put("payload", innerPayload); signaturePayload.put("merchant_id", ""); // Put your Merchant ID here signaturePayload.put("customer_id", ""); // Put Customer ID here signaturePayload.put("timestamp", ""); // Time when request is created in milliseconds. } catch (Exception e) { e.printStackTrace(); } return sdkPayload; } ``` #### Kotlin Code Snippet: ```kotlin private fun createInitiatePayload(): JSONObject { val sdkPayload = JSONObject() val innerPayload = JSONObject() try { // generating inner payload innerPayload.put("action", "initiate") innerPayload.put("merchantKeyId", "") // Put your Merchant ID here innerPayload.put("clientId", "CLIENT_ID") // Put your Client ID here innerPayload.put("environment", "production") innerPayload.put("issuingPsp", "YES_BIZ") innerPayload.put("signature", "....") // Generated signature for signature payload innerPayload.put("signaturePayload", signaturePayload) // block:start:generatingRequestId sdkPayload.put("requestId", ""+ UUID.randomUUID()) // block:end:generatingRequestId sdkPayload.put("service", "in.juspay.hyperapi") sdkPayload.put("payload", innerPayload) signaturePayload.put("merchant_id", "") // Put your Merchant ID here signaturePayload.put("customer_id", "") // Put Customer ID here signaturePayload.put("timestamp", "") // Time when request is created in milliseconds. } catch (e: Exception) { e.printStackTrace() } return sdkPayload } ``` ### Initiate Parameters ## Request Payload - **RequestId**: - Description: Unique uuid-v4 string - Value: $requestId - Tags: String, Mandatory - **Service**: - Description: Value: in.juspay.hyperapi - Tags: String, Mandatory - **Payload**: - Description: Parameters required to call Hyper SDK API - Value: - **Action**: - Description: Operation to be performed in the SDK. Should be initiate for this call. - Value: Value: initiate - Tags: String, Mandatory - **ClientId**: - Description: Client Id assigned by juspay. Usual convention is merchant_id - Value: Example: stock - Tags: String, Mandatory - **Environment**: - Description: Environment to be used for the session. Accepted values are 'sandbox' or 'production' - Value: Example: sandbox - Tags: String, Mandatory - **IssuingPsp**: - Description: Bank on which the merchant has been onboarded. - Value: Example: YES_BIZ - Tags: String, Mandatory - **MerchantKeyId**: - Description: Key ID to identify the public-private key pair used for signature generation. - Value: Example: 1234 - Tags: String, Mandatory - **Signature**: - Description: Generated signature for signature payload. See signature generation process in pre-requisites section. - Tags: String, Mandatory - **SignaturePayload**: - Description: Signature payload is a stringified JSON of the details mentioned in the below table. - Value: - **Merchant_id**: - Description: Unique identifier associated with an account created by juspay. - Value: Example: stock - Tags: String, Mandatory - **Customer_id**: - Description: Any unique reference associated with your customer. - Value: Example: abcde12345 - Tags: String, Mandatory - **Timestamp**: - Description: Time when request is created in milliseconds. - Value: Example: 1665996901100 - Tags: String, Mandatory - Tags: String, Mandatory - **ShouldCreateCustomer**: - Description: Value: true - Tags: Boolean, Mandatory - Tags: JSON, Mandatory ## Response Payload - **RequestId**: - Description: Unique uuid-v4 string - Value: $requestId - Tags: String, Mandatory - **Service**: - Description: Value: in.juspay.hyperapi - Tags: String, Mandatory - **Payload**: - Description: Parameters required to call Hyper SDK API - Value: - **Action**: - Description: Operation performed in the SDK. - Value: Value: initiate - Tags: String - **Status**: - Description: Status of the Operation. - Value: Possible values : SUCCESS / FAILURE - Tags: String - Tags: JSON, Mandatory > **Note** > [Click here](../miscellaneous/additional-parameters) for additional initiate parameters #### Code Snippets: - #### Java Code Snippet: ```java { "requestId": "8cbc3fad-8b3f-40c0-ae93-2d7e75a8624a", "service": "in.juspay.hyperapi", "payload": { "action": "initiate", "merchantKeyId": "", "clientId": "", "signature": "", "signaturePayload": "", "environment": "sandbox", "upiEnvironment": "sandbox" "issuingPsp": "YES_BIZ", "shouldCreateCustomer": true, "logLevel": 1 } } "signaturePayload": { "merchant_id": "stock", "customer_id": "abcde12345", "timestamp": "1668389349848" } ``` #### Kotlin Code Snippet: ```kotlin { "requestId": "8cbc3fad-8b3f-40c0-ae93-2d7e75a8624a", "service": "in.juspay.hyperapi", "payload": { "action": "initiate", "merchantKeyId": "", "clientId": "", "signature": "", "signaturePayload": "", "environment": "sandbox", "upiEnvironment": "sandbox" "issuingPsp": "YES_BIZ", "shouldCreateCustomer": true, "logLevel": 1 } } "signaturePayload": { "merchant_id": "stock", "customer_id": "abcde12345", "timestamp": "1668389349848" } ``` ### Step 3 Create CallbackHandler During its lifecycle, SDK emits multiple events to communicate about the transaction status. All of these events are received by an instance of `HyperPaymentsCallbackAdapter`. This callback handler is passed as the second argument to the initiate API call. #### Code Snippets: - #### Java Code Snippet: ```java final HyperPaymentsCallbackAdapter callbackAdapter = new HyperPaymentsCallbackAdapter() { @Override public void onEvent(JSONObject data, JuspayResponseHandler handler) { try { // block:start:handle-sdk-response String event = data.getString("event"); // block:start:show-loader if (event.equals("show_loader")) { // Show some loader here } // block:end:show-loader // block:start:hide-loader else if (event.equals("hide_loader")) { // Hide Loader } // block:end:hide-loader // block:start:initiate-result else if (event.equals("initiate_result")) { // Get the response JSONObject response = data.optJSONObject("payload"); } // block:end:initiate-result // block:start:process-result else if (event.equals("process_result")) { // Get the response JSONObject response = data.optJSONObject("payload"); //Merchant handling } // block:end:process-result // block:start:log-stream else if (event.equals("log_stream")){ Log.i("=>Clickstream", data.toString()); } // block:end:log-stream // block:start:session-expiry else if (event.equals("session_expiry")){ // Handle Session Expiry } // block:end:session-expiry } catch (Exception e) { // merchant code... } // block:end:handle-sdk-response } }; ``` #### Kotlin Code Snippet: ```kotlin private fun createHyperPaymentsCallbackAdapter(): HyperPaymentsCallbackAdapter { return object : HyperPaymentsCallbackAdapter() { override fun onEvent(jsonObject: JSONObject, responseHandler: JuspayResponseHandler?) { try { // block:start:handle-sdk-response val event = jsonObject.getString("event") // block:start:hide-loader if (event == "hide_loader") { // Hide Loader } // block:end:hide-loader // block:start:show-loader else if (event == "show_loader") { // Show some loader } // block:end:show-loader // block:start:initiate-result else if (event == "initiate_result") { val innerPayload = jsonObject.optJSONObject("payload") } // block:end:initiate-result // block:start:process-result else if (event == "process_result") { val innerPayload = jsonObject.optJSONObject("payload") } // block:end:process-result // block:start:log-stream else if (event == "log_stream") { val innerPayload = jsonObject.optJSONObject("payload") } // block:end:log-stream // block:start:session-expiry else if (event == "session_expiry") { // Handle Session Expiry } // block:end:session-expiry } catch (e: Exception) { // merchant code... } // block:end:handle-sdk-response } } } ``` ### Step 4 Call initiate The final step is to call the `Initiate SDK API`. The initiate method takes two parameters: `InitiatePayload` and `HyperPaymentsCallbackAdapter`. Use the functions created in the above steps to create the parameters > **Warning** > Initiate is a fire-and-forget call. For every HyperService instance you should **call initiate only once.** #### Code Snippets: - #### Java Code Snippet: ```java hyperInstance.initiate(initiateData, callbackAdapter); ``` #### Kotlin Code Snippet: ```kotlin private fun initiatePaymentsSDK() { if (!hyperServicesHolder!!.isInitiated) { initiatePayload = createInitiatePayload() hyperServicesHolder!!.initiate(createInitiatePayload()) } } ```