---
page_title: 3. Initialize SDK
product: EC Headless
platform: iOS
page_source: https://juspay.io/in/docs/ec-headless/ios/base-sdk-integration/initiating-sdk
llms_txt: https://juspay.io/in/docs/llms.txt
product_llms_txt: https://juspay.io/in/docs/ec-headless/llms.txt
---


## 3. Initiating the SDK



To initialise the SDK, client needs to call the `initiate` SDK API. The initiate api call boots up Express Checkout SDK and makes it ready for all other operations

Follow the below steps to make an initiate SDK call

> **Error**
> Initiate is to be called in viewDidLoad function of the home screen view controller. Not following this will lead to increased latency.




### Step 3.1. Import HyperSDK


Import the HyperSDK namespace to get access to HyperServices class in your code



#### Code Snippets: -

#### Swift Code Snippet:

```swift
import HyperSDK
```

#### ObjectiveC Code Snippet:

```objectivec
#import <HyperSDK/HyperSDK.h>
```



### Step 3.2. Create an instance of HyperServices


Express Checkout SDK exposes the `HyperServices` class. Create an object of this class for all upcoming operations



#### Code Snippets: -

#### Swift Code Snippet:

```swift
let hyperInstance = HyperServices();
```

#### ObjectiveC Code Snippet:

```objectivec
self.hyperInstance = [[HyperServices alloc] init];
```



### Step 3.3. Create Initiate payload


Initiate API takes three 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 [initiate payload](https://docs.juspay.in/ec-headless/ios/payloads/payload-samples)for information about the description and sample payload.



#### Code Snippets: -

#### Swift Code Snippet:

```swift
func createInitiatePayload() -> [String: Any] {
        let innerPayload : [String: Any] = [
            "action": "initiate",
            "merchantId": "<MERCHANT_ID>",
            "clientId": "<CLIENT_ID>",
            "customerId": "<CUSTOMER_ID>",
            "xRoutingId": "<X_ROUTING_ID>",
            "environment": "prod"
        ];

        let sdkPayload : [String: Any] = [
            "requestId": UUID().uuidString,
            "service": "in.juspay.hyperapi",
            "payload": innerPayload
        ]

        return sdkPayload
    }
```

#### ObjectiveC Code Snippet:

```objectivec
- (NSDictionary *)createInitiatePayload {
        NSDictionary *innerPayload = @{
            @"action": @"initiate",
            @"merchantId": @"<MERCHANT_ID>",
            @"clientId": @"<CLIENT_ID>",
            @"customerId": @"<CUSTOMER_ID>",
            @"xRoutingId": @"<X_ROUTING_ID>",
            @"environment": @"prod"
        };

        NSDictionary *sdkPayload = @{
            @"requestId": @"12398b5571d74c3388a74004bc24370c",
            @"service": @"in.juspay.hyperapi",
            @"payload": innerPayload
        };

        return sdkPayload;
    }
```



### Step 3.4. 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: -

#### Swift Code Snippet:

```swift
func hyperCallbackHandler(response : (Optional<Dictionary<String, Any>>)) {
        if let data = response, let event = data["event"] as? String {
            if (event == "hide_loader") {
                // hide loader
            }
            // Handle Process Result
            // block:start:handle-process-result
            else if (event == "process_result") {
                let error = data["error"] as! Bool

                let innerPayload = data["payload"] as! [ String: Any ]
                let status = innerPayload["status"] as! String
                let pi = innerPayload["paymentInstrument"] as? String
                let pig = innerPayload["paymentInstrumentGroup"] as? String

                if (!error) {
                    // txn success, status should be "charged"
                    // process data -- show pi and pig in UI maybe also?
                    // example -- pi: "PAYTM", pig: "WALLET"
                    // call orderStatus once to verify (false positives)
                } else {

                    let errorCode = data["errorCode"] as! String
                    let errorMessage = data["errorMessage"] as! String
                    switch (status) {
                        case "backpressed":
                            // user back-pressed from checkout screen without initiating any txn
                            break;
                        case "user_aborted":
                            // user initiated a txn and pressed back
                            // poll order status
                            break;
                        case "pending_vbv", "authorizing":
                            // txn in pending state
                            // poll order status until backend says fail or success
                            break;
                        case "authorization_failed", "authentication_failed", "api_failure":
                            // txn failed
                            // poll orderStatus to verify (false negatives)
                            break;
                        case "new":
                            // order created but txn failed
                            // also failure
                            // poll order status
                            break;
                        default:
                            // unknown status, this is also failure
                            // poll order status
                            break;
                    }
                }
            }
            // block:end:handle-process-result
        }

    }
```

#### ObjectiveC Code Snippet:

```objectivec
self.hyperCallbackHandler = ^(NSDictionary<NSString *,id> * _Nullable response) {
        NSDictionary *data = response;
        NSString *event = data[@"event"];

        if ([event isEqualToString:@"hide_loader"]) {
            // hide loader
        }
        // Handle Process Result
        // block:start:handle-process-result

        else if ([event isEqualToString:@"process_result"]) {
            BOOL error = [data[@"error"] boolValue];

            NSDictionary *innerPayload = data[@"payload"];
            NSString *status = innerPayload[@"status"];
            NSString *pi = innerPayload[@"paymentInstrument"];
            NSString *pig = innerPayload[@"paymentInstrumentGroup"];

            if (!error) {
                // txn success, status should be "charged"
                // process data -- show pi and pig in UI maybe also?
                // example -- pi: "PAYTM", pig: "WALLET"
                // call orderStatus once to verify (false positives)
            } else {

                NSString *errorCode = data[@"errorCode"];
                NSString *errorMessage = data[@"errorMessage"];
                if([status isEqualToString:@"backpressed"]) {
                    // user back-pressed from checkout screen without initiating any txn
                }
                else if ([status isEqualToString:@"backpressed"]) {
                    // user initiated a txn and pressed back
                    // poll order status
                } else if ([status isEqualToString:@"pending_vbv"] || [status isEqualToString:@"authorizing"]) {
                    // txn in pending state
                    // poll order status until backend says fail or success
                } else if ([status isEqualToString:@"authorization_failed"] || [status isEqualToString:@"authentication_failed"] || [status isEqualToString:@"api_failure"]) {
                    // txn failed
                    // poll orderStatus to verify (false negatives)
                } else if([status isEqualToString:@"new"]) {
                    // order created but txn failed
                    // also failure
                    // poll order status
                } else {
                    // unknown status, this is also failure
                    // poll order status
                }
            }
        }
        // block:end:handle-process-result
    };
```



### Step 3.5. Call initiate


The final step is to call the `Initiate SDK API`.

The initiate method takes three parameters: `ViewController` and `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: -

#### Swift Code Snippet:

```swift
hyperInstance.initiate(
            self,
            payload: createInitiatePayload(),
            callback: hyperCallbackHandler
        )
```

#### ObjectiveC Code Snippet:

```objectivec
NSDictionary *initPayload = [self createInitiatePayload];
        [self.hyperInstance initiate:self payload:initPayload callback:self.hyperCallbackHandler];
```


---

## Complete Code Reference

The following code files are referenced in the steps above:

### ViewController.swift

```
//
//  ViewController.swift
//  juspay-sdk-integration-swift
//
//
import UIKit

// Importing Hyper SDK
// block:start:import-hyper-sdk

import HyperSDK
// block:end:import-hyper-sdk


class ViewController: UIViewController {

    // Creating an object of HyperServices class.
    // block:start:create-hyper-services-instance

    let hyperInstance = HyperServices();
    // block:end:create-hyper-services-instance

    
    override func viewDidLoad() {
        super.viewDidLoad()
    }


    // Creating initiate payload JSON object
    // block:start:create-initiate-payload

    func createInitiatePayload() -> [String: Any] {
        let innerPayload : [String: Any] = [
            "action": "initiate",
            "merchantId": "<MERCHANT_ID>",
            "clientId": "<CLIENT_ID>",
            "customerId": "<CUSTOMER_ID>",
            "xRoutingId": "<X_ROUTING_ID>",
            "environment": "prod"
        ];

        let sdkPayload : [String: Any] = [
            "requestId": UUID().uuidString,
            "service": "in.juspay.hyperapi",
            "payload": innerPayload
        ]

        return sdkPayload
    }
    // block:end:create-initiate-payload

    // Creating HyperPaymentsCallbackAdapter
    // This callback will get all events from hyperService instance
    // block:start:create-hyper-callback

    func hyperCallbackHandler(response : (Optional<Dictionary<String, Any>>)) {
        if let data = response, let event = data["event"] as? String {
            if (event == "hide_loader") {
                // hide loader
            }
            // Handle Process Result
            // block:start:handle-process-result
            else if (event == "process_result") {
                let error = data["error"] as! Bool

                let innerPayload = data["payload"] as! [ String: Any ]
                let status = innerPayload["status"] as! String
                let pi = innerPayload["paymentInstrument"] as? String
                let pig = innerPayload["paymentInstrumentGroup"] as? String

                if (!error) {
                    // txn success, status should be "charged"
                    // process data -- show pi and pig in UI maybe also?
                    // example -- pi: "PAYTM", pig: "WALLET"
                    // call orderStatus once to verify (false positives)
                } else {

                    let errorCode = data["errorCode"] as! String
                    let errorMessage = data["errorMessage"] as! String
                    switch (status) {
                        case "backpressed":
                            // user back-pressed from checkout screen without initiating any txn
                            break;
                        case "user_aborted":
                            // user initiated a txn and pressed back
                            // poll order status
                            break;
                        case "pending_vbv", "authorizing":
                            // txn in pending state
                            // poll order status until backend says fail or success
                            break;
                        case "authorization_failed", "authentication_failed", "api_failure":
                            // txn failed
                            // poll orderStatus to verify (false negatives)
                            break;
                        case "new":
                            // order created but txn failed
                            // also failure
                            // poll order status
                            break;
                        default:
                            // unknown status, this is also failure
                            // poll order status
                            break;
                    }
                }
            }
            // block:end:handle-process-result
        }

    }
    // block:end:create-hyper-callback

    
    @IBAction func initiatePayments(_ sender: Any) {
        // Calling initiate on hyperService instance to boot up payment engine.
        // block:start:initiate-sdk
        
        hyperInstance.initiate(
            self,
            payload: createInitiatePayload(),
            callback: hyperCallbackHandler
        )
        // block:end:initiate-sdk
    }


    // Creating process payload JSON object
    // block:start:process-sdk-call

    if hyperInstance?.isInitialised() ?? false {
     hyperInstance.process(processPayload)               
    }
    // block:end:process-sdk-call
    
}


```

### ViewController.m

```
//
//  ViewController.swift
//  juspay-sdk-integration-swift
//
//
import UIKit

// Importing Hyper SDK
// block:start:import-hyper-sdk

#import <HyperSDK/HyperSDK.h>
// block:end:import-hyper-sdk


class ViewController: UIViewController {

    // Creating an object of HyperServices class.
    // block:start:create-hyper-services-instance

    self.hyperInstance = [[HyperServices alloc] init];
    // block:end:create-hyper-services-instance

    
    override func viewDidLoad() {
        super.viewDidLoad()
    }


    // Creating initiate payload JSON object
    // block:start:create-initiate-payload

    - (NSDictionary *)createInitiatePayload {
        NSDictionary *innerPayload = @{
            @"action": @"initiate",
            @"merchantId": @"<MERCHANT_ID>",
            @"clientId": @"<CLIENT_ID>",
            @"customerId": @"<CUSTOMER_ID>",
            @"xRoutingId": @"<X_ROUTING_ID>",
            @"environment": @"prod"
        };

        NSDictionary *sdkPayload = @{
            @"requestId": @"12398b5571d74c3388a74004bc24370c",
            @"service": @"in.juspay.hyperapi",
            @"payload": innerPayload
        };

        return sdkPayload;
    }
    // block:end:create-initiate-payload

    // Creating HyperPaymentsCallbackAdapter
    // This callback will get all events from hyperService instance
      //block:start:create-hyper-callback

    self.hyperCallbackHandler = ^(NSDictionary<NSString *,id> * _Nullable response) {
        NSDictionary *data = response;
        NSString *event = data[@"event"];

        if ([event isEqualToString:@"hide_loader"]) {
            // hide loader
        }
        // Handle Process Result
        // block:start:handle-process-result

        else if ([event isEqualToString:@"process_result"]) {
            BOOL error = [data[@"error"] boolValue];

            NSDictionary *innerPayload = data[@"payload"];
            NSString *status = innerPayload[@"status"];
            NSString *pi = innerPayload[@"paymentInstrument"];
            NSString *pig = innerPayload[@"paymentInstrumentGroup"];

            if (!error) {
                // txn success, status should be "charged"
                // process data -- show pi and pig in UI maybe also?
                // example -- pi: "PAYTM", pig: "WALLET"
                // call orderStatus once to verify (false positives)
            } else {

                NSString *errorCode = data[@"errorCode"];
                NSString *errorMessage = data[@"errorMessage"];
                if([status isEqualToString:@"backpressed"]) {
                    // user back-pressed from checkout screen without initiating any txn
                }
                else if ([status isEqualToString:@"backpressed"]) {
                    // user initiated a txn and pressed back
                    // poll order status
                } else if ([status isEqualToString:@"pending_vbv"] || [status isEqualToString:@"authorizing"]) {
                    // txn in pending state
                    // poll order status until backend says fail or success
                } else if ([status isEqualToString:@"authorization_failed"] || [status isEqualToString:@"authentication_failed"] || [status isEqualToString:@"api_failure"]) {
                    // txn failed
                    // poll orderStatus to verify (false negatives)
                } else if([status isEqualToString:@"new"]) {
                    // order created but txn failed
                    // also failure
                    // poll order status
                } else {
                    // unknown status, this is also failure
                    // poll order status
                }
            }
        }
        // block:end:handle-process-result
    };
    //block:end:create-hyper-callback


    
    @IBAction func initiatePayments(_ sender: Any) {
        // Calling initiate on hyperService instance to boot up payment engine.
        // block:start:initiate-sdk
        
        NSDictionary *initPayload = [self createInitiatePayload];
        [self.hyperInstance initiate:self payload:initPayload callback:self.hyperCallbackHandler];
        // block:end:initiate-sdk
    }


    // Creating process payload JSON object
    // block:start:process-sdk-call

    if ([hyperInstance isInitialised]) {
          [hyperInstance process:processPayload];       
    }
    // block:end:process-sdk-call
    
}


```


---

## See Also

- [2. Creating a Customer](https://juspay.io/in/docs/ec-headless/ios/base-sdk-integration/creating-a-customer)
- [4. Rendering the Checkout Screen](https://juspay.io/in/docs/ec-headless/ios/base-sdk-integration/rendering-the-checkout-screen)