Initiate

To serve dynamically changing requirements for the payments ecosystem, HyperSDK uses a JS engine to improve user experience and enable faster iterations.

The Initiate API starts up the JS engine and enables it to improve the performance of the subsequent SDK API calls.

👍
NOTE
It is highly recommended to call Initiate SDK from the order summary page (at least 5 seconds before starting the payment page) for a seamless user experience. This is to optimize background API calls to fetch/ create customer, refresh wallet balances, and fetch enabled payment methods.

Inputs

The Initiate API methods are described below for Android, iOS, and React Native. Each of the three methods require two inputs as arguments:

A JSON object which contains the Initiate Payload parameters for the entire session and remains static throughout one SDK instance lifetime.
A callback function (or listener), which is an interface method to handle various outputs/events in responses returned to the SDK resulting from API calls. The name of this method for each OS is:
- Android -- HyperPaymentsCallbackAdapter
- iOS -- HyperPaymentsCallback (contains a Dictionary as parameter)
- React Native -- 'HyperEvent' listener (listens to events from HyperSDK- see below)

The following events are handled by the callback (Android or iOS) or listener (only for React Native):
- show_loader: To show a loader for the processing state.
- hide_loader: To hide the previously shown loader.
- initiate_result: Result of initiate done.
- process_result: Result of the process operation done in Process.

Integration Sample

hyperInstance.initiate(initiationPayload, new HyperPaymentsCallbackAdapter() {
   @Override
   public void onEvent(JSONObject data, JuspayResponseHandler handler) {
       try {
         String event = data.getString("event");
         if (event.equals("show_loader")) {
           // Show some loader here
         } else if (event.equals("hide_loader")) {
           // Hide Loader
         } else if (event.equals("initiate_result")) {
           // Get the response
           JSONObject response = data.optJSONObject("payload");
         } else if (event.equals("process_result")) {
           // Get the response
           JSONObject response = data.optJSONObject("payload");
           //Merchant handling
         }
       } catch (Exception e) {
         // merchant code...
       }  
    }
});

hyperInstance.initiate(initiationPayload, object : HyperPaymentsCallbackAdapter() {
        fun onEvent(data: JSONObject, handler: JuspayResponseHandler?) {
            try {
                val event: String = data.getString("event")
                if (event == "show_loader") {
                    // Show some loader here
                } else if (event == "hide_loader") {
                    // Hide Loader
                } else if (event == "initiate_result") {
                    // Get the response
                    val response: JSONObject = data.optJSONObject("payload")
                } else if (event == "process_result") {
                    // Get the response
                    val response: JSONObject = data.optJSONObject("payload")
                    //Merchant handling
                }
            } catch (e: Exception) {
                // merchant code...
            }
        }
    })

self.hyperInstance.initiate(self, initiationPayload, callback: { [unowned self] (response) in
     if let data = response {
         let event = data["event"] as? String ?? ""
         if event == "show_loader" {
           // Show some loader here
         } else if event == "hide_loader" {
           // Hide Loader
         } else if event == "initiate_result" {
           // Get the payload
           let payload = response?["payload"]
         } else if event == "process_result" {
           // Get the payload
           let payload = response?["payload"]
           //Merchant handling
         }
     } else {
       //Error handling
     }
})

[self.hyperInstance initiate:self payload:initiationPayload callback:^(NSDictionary *data) {
      if (data && data[@"event"]) {
          if ([event isEqualToString:@"show_loader"]) {
              // Show some loader here
          } else if ([event isEqualToString:@"hide_loader"]) {
              // Hide Loader
          } else if ([event isEqualToString:@"initiate_result"]) {
              // Get the payload
              NSDictionary *payload = response["payload"];
          } else if ([event isEqualToString:@"process_result"]) {
              // Get the payload
              NSDictionary *payload = response["payload"];
              // Merchant handling
          }
      } else {
        //Error handling
     }
}];

HyperSdkReact.initiate(JSON.stringify(initiatePayload));

The React Native method uses a listener instead of a callback to receive and handle responses to the SDK resulting from API calls:

HyperEvent listener (click to view)

Listens to events from HyperSDK

The Hyper SDK Native Module will be emitting all the relevant events to JS via RCTDeviceEventEmitter and JavaScript modules can then register to receive events by invoking addListener on the NativeEventEmitter class in the componentDidMount() method with the event name 'HyperEvent'. The listener will return a stringified JSON response (resp).

Note: The listener can be removed when the React component unmounts in componentWillUnmount() method.
componentDidMount() {
   ...
   const eventEmitter = new NativeEventEmitter(NativeModules.HyperSdkReact);
   this.eventListener = eventEmitter.addListener('HyperEvent', (resp) => {
     var data = JSON.parse(resp);
     var event: string = data.event || '';
     switch (event) {
       case 'show_loader':
         // show some loader here
         break;
       case 'hide_loader':
         // hide the loader
         break;
       case 'initiate_result':
         var payload = data.payload || {};
         console.log('initiate_result: ', payload);
         // merchant code
         ...
         break;
       case 'process_result':
         var payload = data.payload || {};
         console.log('process_result: ', payload);
         // merchant code
         ...
         break;
       default:
         console.log('Unknown Event', data);
     }
     ...
   });
   ...
 }
 componentWillUnmount() {
   ...
   this.eventListener.remove();
   ...
 }
Note: When using Hyper SDK with React Native on Android hardware, special code snippets are needed for handling back-press and permissions control. Check here for information.

📘
Where to Call Initiate?

Android: In the onCreate() method of your application's host activity

iOS: Should be called only once on the viewDidLoad of the host View Controller. Note that this method takes View Controller (host view controller) as an input argument in addition to the JSON object and callback described above,

React: be called on the render of the host screen. Result of the call (whether success or failure) is provided in the Hyper Event listener.

Each of these methods will boot up the SDK and start the Hyper engine.

Note: I'm not sure if this "Where to call Initiate?" note should be updated to the following or not. Maybe someone can help me on this.

📘
Where to call Initiate?

Android: In the onCreate() method of your application's main activity

iOS: In application:didFinishLaunchingWithOptions method of the application's AppDelegate class

React

Class Component architecture: In componentDidMount() method

Function Component architecture: In useEffect() hook

Initiate

👍
NOTE

Inputs

Integration Sample

📘
Where to Call Initiate?

📘
Where to call Initiate?

👍NOTE

Inputs

Integration Sample

📘Where to Call Initiate?

📘Where to call Initiate?

👍
NOTE

📘
Where to Call Initiate?

📘
Where to call Initiate?