iOS Loans SDK Integration

Step 1 - Install and Configure

A. Using Cocoapod

smallcase Gateway Loans iOS SDK comes bundled with our primary SDK. It is available as a public cocoa pod dependency.

To install the iOS SDK:

1. add following code to your Podfile
2. run pod install

target '${CLIENT_PROJECT_NAME}' do

  # Comment the next line if you're not using Swift and don't want to use dynamic frameworks
  use_frameworks!
  
  # Add the SCGateway pod dependency and replace ${FRAMEWORK_VERSION}
  # with latest version code (example: 3.11.2).
  pod 'SCGateway', '~> ${FRAMEWORK_VERSION}'
  end

end

B. Using Swift Package Manager

To install the iOS SDK as a Swift Package Dependency to your Xcode project:

i - Select File > Swift Packages > Add Package Dependency

ii - Enter the following repository URL:

https://github.com/smallcase/SCGatewayPackageIos

iii - Decide whether your project accepts updates to a package dependency up to the next major version or up to the next minor version.

Step 2- Environment Setup

To start using the loans SDK, set up the loans SDK with the desired configuration by calling the setup method which is available inside ScLoan class.

ScLoan.instance.setup (config: ScLoanConfig(
    gatewayName : String,
    environment : SCLoanEnvironment
)) { result in
                                        
   switch result {
   case .success(let response):
   //Handle response 
   case .failure(let error):
   //Handle the exception
   } 
}

Params :

1. ScLoanConfig :

   1. gatewayName (required): This is a unique name given to every gateway consumer
      Eg : moneycontrol
   2. environment (required): This defines the Url environment to which all the gateway apis would point to
      Possible values - ScLoanEnvironment.PRODUCTION

📘

Note

Call setup every time there is any change in the setup.
setup must be the first method to be fired. If setup is not called all other methods will not work.

Step 3 - Call the relevant method for each functionality

Based on the action to be performed, trigger the relevant method of ScLoan class.

Interaction Token should be created before calling any Loans related method

All the Loans methods on the SDK instance require an interaction token to be passed as an argument. The JWT token holds the context of user action in the form of Interaction ID. It is a unique, one-time-use ID created each time a borrower wants to interact with their loan via SDK. Learn what & how of interaction ID & token in Glossary & API documentation.

1. apply: start or resume loan application

You can start or resume a loan application by calling the apply method on the SDK.

ScLoan.instance.apply(presentingController: UIViewController, loanInfo: ScLoanInfo(interactionToken: String)) { result in
     switch result {
     case .success(let response):
     //Handle response
     case .failure(let error):
     //Handle error
     }
 }

Params :

1. ScLoanInfo :
   1. interactionToken (required): a unique string you received from the backend in the previous step.
      Go to the next step for response handling

2. pay: repayments (principal, bounced interest, charges due)

For repayment, the gateway flow can be triggered opened by calling the pay method on the SDK -

ScLoan.instance.pay(presentingController: UIViewController, loanInfo: ScLoanInfo(interactionToken: String)) { result in
     switch result {
     case .success(let response):
     //Handle response
     case .failure(let error):
     //Handle error
     }
 }

Params :

1. ScLoanInfo :
   1. interactionToken (required): a unique string you received from the backend in the previous step.
      Go to the next step for response handling

3. withdraw: withdraw un-utilised credit limit

You can withdraw from your approved credit by calling the withdraw method on the SDK.

ScLoan.instance.withdraw(presentingController: UIViewController, loanInfo: ScLoanInfo(interactionToken: String)) { result in
     switch result {
     case .success(let response):
     //Handle response
     case .failure(let error):
     //Handle error
     }
 }

Params :

1. ScLoanInfo :
   1. interactionToken (required): a unique string you received from the backend in the previous step.
      Go to the next step for response handling

4. service: view loan dashboard (aka servicing dashboard)

This will open up Gateway's UI for servicing dashboard where user can view all of their loan details and take any further action (eg. repayment, withdrawal, closure).

ScLoan.instance.service(presentingController: UIViewController, loanInfo: ScLoanInfo(interactionToken: String)) { result in
     switch result {
     case .success(let response):
     //Handle response
     case .failure(let error):
     //Handle error
     }
 }

Params :

1. ScLoanInfo :
   1. interactionToken (required): a unique string you received from the backend in the previous step.
      Go to the next step for response handling

Step 4 - Handle response or error

If the user's intended action is completed, the Future returned by the method will resolve with a success response. Else, if flow ends without action completion, an exception is thrown.

Success responses

ScLoanSuccess is an internal class that denotes a success response on the SDK.
The iOS SDK returns a serialised version of this object whose signature is defined below.

{
  "isSuccess": true,
  "data": {
    "intent": "LOAN_APPLICATION",
    "userId": "string",
    "loanApplication": {
      "status": "<ApplicationStatus>" // possible enum values below
    }
  }
}

{
  "isSuccess": true,
  "data": {
    "intent": "PAYMENT",
    "userId": "string",
    "payment": {
      "status": "<PaymentStatus>"
    }
  }
}

{
  "isSuccess": true,
  "data": {
    "intent": "WITHDRAW",
    "userId": "string",
    "withdraw": {
      "status": "<WithdrawStatus>"
    }
  }
}

// .service() promise will always be rejected with an error.
// This is because there's no specific user intent that should cause a success.

Error response

ScLoanError is an internal class that denotes an error response on the SDK.
The iOS SDK throws a serialised version of this object whose signature is defined below.

{
  "isSuccess": false,
  "code": "number", // enums below
  "message": "string", // enums below
  "data"?: {} // intent specific data point
}

// case where user drops off before applying
{
  "isSuccess": false,
  "code": 1012,
  "message": "user_cancelled",
  "data": {
    "intent": "LOAN_APPLICATION",
    "loanApplication": {
      "lid": "648c66ffc3488a97c9931a2d",
      "status": "SIGN_AGREEMENT"
    },
    "userId": "648c6705ee286538f7bebbbb"
  }
}

// case where loan is active with another platform
{
  "isSuccess": false,
  "code": 3001,
  "message": "existing_loan_found",
  "data": {
    "intent": "LOAN_APPLICATION",
    "userId": "64ad01ba0241316d036519c6"
  }
}

// other error codes bellow

The error code <> message mapping -

👋

Got queries? Ask our AM for an integrations support email. If an email thread exists, post queries as a reply to that.