iOS Build UX SDK

Introduction

The FriendlyScore Connect API Wrapper allows you build custom UX to connect bank accounts by using the FriendlyScore REST API.

Requirements

  1. Xcode 10 or greater
  2. iOS 12.0 or greater
  3. FriendlyScore Client Id & Secret

Quickstart Demo App

Clone and run the demo project from our GitHub repository.

Integrating with FriendlyScore

You can select which environment you want to use the FriendlyScore SDK

EnvironmentDescription
sandboxUse this environment to test your integration
productionUse this environment when deploying the live application

These environments are listed in the SDK as below

1 2 Environment.sandbox Environment.production

Choose the correct FriendlyScore Client Id & Secret based on the environment you are using.

1. Get access token

You can get the access token from the Authentication endpoint.

Your server must communicate with the FriendlyScore server to get the access token. Then your app must communicate with your server to use the access token. The Access token is required to generate a userToken to make user related requests.

Never put your client_secret in the mobile app

2. Create the FriendlyScore Client

Choose the client_id and the environment you want to integrate. You can access the client_id from the FriendlyScore panel

1 2 3 4 5 var environment: Environment = Environment.sandbox var client_id: String = "YOUR_CLIENT_ID" var access_token: String = "access_token_from_step_1" var fsClient: FriendlyScoreClient = FriendlyScoreClient(environment: environment, clientId: client_id, accessToken: access_token)

The fsClient will be required to make other requests

3. Create User Token

You must create userToken in order to make any request for the user.

In order to receive response you must implement closures requestSuccess, requestFailure, otherError.

Required parameters:

userReferenceUnique user reference that identifies user in your systems.
requestSuccessif the status code is between [200,300). Response type UserToken
requestFailureif there was request failure, (status code = 401, 403, 500 etc..). Response type MoyaResponse
otherErrorAny other error such as timeout or unexpected error. Response type Swift.Error?
1 2 3 4 5 6 7 8 9 10 11 var userReference: String = "user_reference" fsClient?.createUserAuthToken( userReference: userReference, requestSuccess: { userToken in self.userToken = userToken.getToken() }, requestFailure: { moyaResponse in let statusCode = moyaResponse.statusCode let data: Data = moyaResponse.data }, otherError: { error in print(error.debugDescription) } )

4. Get List of Banks

You can obtain the list of banks for the user.

In order to receive response you must implement closures requestSuccess, requestFailure, otherError.

Required parameters:

userTokenUser Token obtained from authorization endpoint.
requestSuccessif the status code is between [200,300). Response type Array<UserBank>
requestFailureif there was request failure, (status code = 401, 403, 500 etc..). Response type MoyaResponse
otherErrorAny other error such as timeout or unexpected error. Response type Swift.Error?
1 2 3 4 5 6 7 8 9 10 11 var userToken: String = "User Token obtained from authorization endpoint" fsClient?.fetchBankList( userToken: userToken, requestSuccess: { bankList in }, requestFailure: { moyaresponse in let statusCode = moyaResponse.statusCode let data: Data = moyaResponse.data }, otherError: { error in print(error.debugDescription) } )

Find the important values for each bank that will be required for the UI and future requests. Below is an example of how to retrieve values for the first bank from the list.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 //Showing the important variables for the first bank var selectedBank: UserBank = self.bankList![0] //Slug of the bank. Will be required for other end points var bankSlug: String = selectedBank.bank.slug //If the user has connected accounts from this bank var connected: Bool? = selectedBank.connected! //The flag when true indicates the bank APIs are available var isActive: Bool? = selectedBank.bank.is_active //Url for the logo of the selected bank var bankLogoUrl: URL? = selectedBank.bank.logo //Max number of months in the past to access data var maxMonthsInPast: Int = (selectedBank.bank.bank_configuration?.transactions_consent_from!)! //Max number of months in the future to access data var maxMonthsInFuture: Int = (selectedBank.bank.bank_configuration?.transactions_consent_to!)! //Accounts for the user, if the user has connected the account var bankAccountList: Array<BankAccount> = bankList[0].accounts;

The bankSlug value in the code block above is used across all the endpoints to build the rest of the user journey.

The numberOfMonthsInPast and numberOfMonthsInFuture variables in the block above are the maximum number of months in past and future for which account information can be accessed. You must use these values to calculate timestamps for future requests.

4. Get Bank Consent Screen Information

Once the user has selected a bank from the list you must show the user the necessary information, as required by the law.

In order to receive response you must implement closures requestSuccess, requestFailure, otherError.

Required parameters:

userTokenUser Token obtained from authorization endpoint.
bankSlugSlug for the bank user has selected from the list of banks.
transactionFromTimeStampInSecTime stamp in seconds. Set to null to use default.
transactionToTimeStampInSecTime stamp in seconds. Set to null to use default.
requestSuccessif the status code is between [200,300). Response type ConsentScreenInformation
requestFailureif there was request failure, (status code = 401, 403, 500 etc..). Response type MoyaResponse
otherErrorAny other error such as timeout or unexpected error. Response type Swift.Error?
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 // The `ConsentScreenInformation` includes 2 objects `metadata` and `consents`. // You can use information in `metadata` to build your custom consent information text. // The `consents` object provides ready-to-use text to build the consent screen. fsClient?.fetchConsentScreenInformation( userToken: self.userToken!, slug: selectedBank.bank.slug, transactionFromTimeStampInSec: dateFrom, transactionToTimeStampInSec: dateTo, requestSuccess: { consentScreenInfo in print(consentScreenInfo.metadata?.terms_and_condition_url) print(consentScreenInfo.consents) }, requestFailure: { failureResponse in let statusCode: Int = failureResponse.statusCode let responseData: Data = failureResponse.data }, otherError: { error in print(error.debugDescription) })

6. Get Bank Flow Url

Make this request from the consent screen after the user has seen all the information that will is being requested.

You must make this request to get the url to open the Bank Flow for users to authorize access account information.

In order to receive response you must implement closures requestSuccess, requestFailure, otherError.

Required parameters:

userTokenUser Token obtained from authorization endpoint
bankSlugSlug for the bank user has selected from the list of banks
transactionFromTimeStampInSecTime stamp in seconds. Use the same value as used in the Consent screen endpoint. Set to null to use default
transactionToTimeStampInSecTime stamp in seconds. Use the same value as used in the Consent screen endpoint. Set to null to use default.
requestSuccessif the status code is between [200,300). Response type BankFlowUrl
requestFailureif there was request failure, (status code = 401, 403, 500 etc..). Response type MoyaResponse
otherErrorAny other error such as timeout or unexpected error. Response type Swift.Error?
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 fsClient?.fetchBankFlowUrl( userToken: userToken, slug: bankSlug, transactionFromTimeStampInSec: dateFrom, transactionToTimeStampInSec: dateTo, requestSuccess: { bankFlowUrl in print( bankFlowUrl.url) }, requestFailure: { failureResponse in let statusCode: Int = failureResponse.statusCode let responseData: Data = failureResponse.data }, otherError: { error in print(error.debugDescription) } )

From BankFlowUrl extract the url value and trigger it to start the authorization process with the bank.

7. Redirect back to the app

The user is redirected back to your app after a user successfully authorizes, cancels the authorization process or any other error during the authorization.

Your app must handle redirection for:

/openbanking/codesuccessful authorization by user. It should have parameters bank_slug
/openbanking/errorerror in authorization or user did not complete authorization. It should have 2 parameters: bank_slug and error

In order to handle redirection properly, listen to url in the function application(_:open:options:):

1 2 3 4 5 6 7 func application( _ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool { //Extract url parameters return true }

8. Adding URL Types

Go to the Redirects section of the FriendlyScore developer console and provide your Bundle Identifier.

Navigate to your app target, create new URL Types object and add your bundle identifier to Identifier and URL Schemes field, as below:

8. Delete Account Consent

Make this request to allow the user to delete consent to access account information.

In order to receive response you must implement closures requestSuccess, requestFailure, otherError.

Required parameters:

userTokenUser Token obtained from authorization endpoint.
bankSlugSlug for the bank
requestSuccessif the status code is between [200,300). Response type Void
requestFailureif there was request failure, (status code = 401, 403, 500 etc..). Response type MoyaResponse
otherErrorAny other error such as timeout or unexpected error. Response type Swift.Error?
1 2 3 4 5 6 7 8 9 fsClient?.deleteBankConsent( userToken: userToken, slug: bankSlug, requestSuccess: { _ in }, requestFailure: { moyaresponse in let statusCode = moyaResponse.statusCode }, otherError: { error in print(error.debugDescription) } )

Was this article helpful?

Friendly Score UK Ltd.

52 Brook Street 1st Floor, Mayfair

London W1K 5DS

Call us on +44 20 3709 6726

Company registered in England

Company number 09168668, ICO ZA111687

VAT registration number 206 9758 80

Authorised and Regulated by the Financial Conduct Authority. (FRN: 781963)