Android 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. Install or update Android Studio to version 3.2 or greater
  2. We support Android 5.0 and greater
  3. FriendlyScore Client Id & Secret

QuickStart

The easiest way to get started is to clone the GitHub repository. Please follow the instructions below to provide the necessary configuration and to understand the flow.

Getting Set up

Add the following values to your Project Level build.gradle file

In your project-level Gradle file (build.gradle), add rules to include the Android Gradle plugin. The version should be equal to or greater than 3.5.3. You must add jitpack to your repositories as declared below

1 2 3 4 5 6 7 8 9 10 11 buildscript { ... dependencies { classpath 'com.android.tools.build:gradle:3.5.3' } } allprojects { repositories { maven { url 'https://jitpack.io' } } }

FriendlyScore Configuration

Add the following values to your app-level build.gradle file(In the demo app/build.gradle)

1 2 3 4 5 6 7 android { ... compileOptions { sourceCompatibility 1.8 targetCompatibility 1.8 } }

In your module or app-level gradle file (In the demo app/build.gradle) please add the FriendlyScore Android SDK library listed below to your list of dependencies

1 2 3 4 dependencies { ... implementation 'com.github.friendlyscore:friendlyscore-android-connect-api-wrapper:0.1.0' }

Integrating with FriendlyScore

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

EnvironmentDefinitions
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 Environments.SANDBOX Environments.PRODUCTION

Choose the correct FriendlyScore Client Id and Secret based on the environment you are using. Follow the steps below to integrate FriendlyScore:

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 6 7 8 9 10 11 12 /** * * @param environment * @param client_id * @param access_token */ Environment environment = Environment.SANDBOX String client_id = "YOUR_CLIENT_ID" String access_token = "access_token_from_step_1" final FriendlyScoreClient fsClient = createFriendlyScoreClient(environment, client_id, 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 customer. In order to receive response you must implement the ConnectRequestCallback<UserAuthSuccessResponse>.

Save UserToken to make other requests to the API

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 public ConnectRequestErrorHandler.ConnectRequestCallback<UserAuthSuccessResponse> userAuthListener = new ConnectRequestErrorHandler.ConnectRequestCallback<UserAuthSuccessResponse>() { @Override public void success(Response<UserAuthSuccessResponse> response) { UserAuthSuccessResponse userAuthSuccessResponse = response.body(); //Save this token to make other requests for the user userToken = userAuthSuccessResponse.getToken(); } @Override public void unauthenticated(Response<?> response) { //Status Code 401 } @Override public void unauthorized(Response<?> response) { //Status Code 403 } @Override public void clientError(Response<?> response) { //Status Code [400, 500) expect 401 & 403 } @Override public void serverError(Response<?> response) { //Status Code 500 } @Override public void networkError(IOException e) { } @Override public void unexpectedError(Throwable t) { } };

Required parameters:

userReferenceUnique user reference that identifies the customer in your systems.
userAuthListener ConnectRequestCallback

Use the FriendlyScoreClient to make the requests

1 fsClient.createUserToken(userReference, userAuthListener);

4. Get List of Banks

You can obtain the list of banks for the customer. In order to receive response you must implement the ConnectRequestCallback<List<UserBank>>.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 public ConnectRequestErrorHandler.ConnectRequestCallback<List<UserBank>> listOfBanksListener = new ConnectRequestErrorHandler.ConnectRequestCallback<List<UserBank>>() { @Override public void success(Response<List<UserBank>> response) { List<UserBank> bankList = response.body(); if (bankList!=null){ //Sample variables for 1st bank from the bank list String bankSlug = bankList.get(0).bank.slug; Log.e(MainActivity.class.getSimpleName(), bankSlug); //Max Number of months in the past, data for this bank can be accessed from int numberOfMonthsInPast = bankList.get(0).bank.bank_configuration.transactions_consent_from; //Max Number of months in the future, data for this bank will be available for int numberOfMonthsInFuture bankList.get(0).bank.bank_configuration.transactions_consent_to; } } ... };

Required parameters:

userTokenUser Token obtained from authorization endpoint.
listOfBanksListenerConnectRequestErrorHandler.ConnectRequestCallback<List>

Use the FriendlyScoreClient to make the requests

1 fsClient.fetchBankList(userToken, listOfBanksListener);

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 24 25 26 27 28 29 //Slug is Unique per bank String bankSlug = bankList.get(0).bank.slug; //Bank Name String bankName = bankList.get(0).bank.name; //Bank Logo Url String bankLogoUrl = bankList.get(0).bank.logo_url; //Bank CountryCode String bankCountryCode = bankList.get(0).bank.country_code; //Bank Type {Personal, Business} String type = bankList.get(0).bank.type; //Max Number of months in the past, data for this bank can be accessed from int numberOfMonthsInPast = bankList.get(0).bank.bank_configuration.transactions_consent_from; //Max Number of months in the future, data for this bank will be available for int numberOfMonthsInFuture bankList.get(0).bank.bank_configuration.transactions_consent_to; // Status if the customer has connected an account at the bank Boolean connectedBank = bankList.get(0).connected //The flag when true indicates the bank APIs are available Boolean isActive = bankList.get(0).bank.is_active //Accounts for the customer, if the customer has connected the accounts at the bank ArrayList<BankAccount> bankAccountList = bankList.get(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.

5. 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 the ConnectRequestCallback<ConsentScreenInformation>

1 2 3 4 5 6 7 public ConnectRequestErrorHandler.ConnectRequestCallback<ConsentScreenInformation> consentScreenCallback = new ConnectRequestErrorHandler.ConnectRequestCallback<ConsentScreenInformation>() { @Override public void success(Response<ConsentScreenInformation> response) { } ... }

Required parameters:

userTokenUser Token obtained from authorization endpoint
bankSlugSlug for the bank user has selected from the list of banks
transactionFromTimeStampInSecSet to null to use default values.
transactionToTimeStampInSecSet to null to use default values.
consentScreenCallbackConnectRequestErrorHandler.ConnectRequestCallback

Make the request below to create the consent screen using the required and regulated information for the bank the user selected

1 fsClient.fetchConsentScreenInformation(userToken, bankSlug, transactionFromTimeStampInSec, transactionToTimeStampInSec, consentScreenCallback);

The ConsentScreenInformation includes two 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.

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 the ConnectRequestCallback<BankFlowUrl>

1 2 3 4 5 6 7 8 9 10 public ConnectRequestErrorHandler.ConnectRequestCallback<BankFlowUrl> bankFlowUrlListener = new ConnectRequestErrorHandler.ConnectRequestCallback<BankFlowUrl>() { /** Called for [200, 300) responses. */ @Override public void success(Response<BankFlowUrl> response) { BankFlowUrl bankFlowUrl = response.body(); Log.e(MainActivity.class.getSimpleName(),bankFlowUrl.url); } ... }

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.
bankFlowUrlListenerConnectRequestErrorHandler.ConnectRequestCallback
1 fsClient.fetchBankFlowUrl(userToken, bankSlug, transactionFromTimeStampInSec, transactionToTimeStampInSec, bankFlowUrlListener);

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

7. Redirect back to the app

Go to the Redirects section of the FriendlyScore developer console and provide your Android Scheme and Android Package

The customer 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 customer. It should have parameters bank_slug
/openbanking/errorerror in authorization or customer did not complete authorization. It should have 2 parameters: bank_slug and error

In order to handle redirection your App manifest AndroidManifest.xml must have activity that is listening for this redirection.

Your activity must declare intent-filter tag with the action and category as shown below the data tag must declare android:host,android:path and android:scheme.

Only edit android:scheme to point to your app.

This value must be the same as the value you set in the developer section of FriendlyScore Console

Do not change android:host and android:path.

These values must be as is below in the code blocks.

For redirection after successful bank account authorization, create an activity with declaration in your manifest as below

1 2 3 4 5 6 7 8 9 10 11 12 13 <activity android:name="BankConnectThankYouRedirect"> <intent-filter android:label=""> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:host="api.friendlyscore.com" android:path="/openbanking/code" android:scheme="com.my.demo.app" /> </intent-filter> </activity>

For redirection after customer cancels or any other error in completing bank account authorization, create an activity with declaration in your manifest as below

1 2 3 4 5 6 7 8 9 10 11 12 13 <activity android:name="BankConnectErrorRedirect"> <intent-filter android:label=""> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:host="api.friendlyscore.com" android:path="/openbanking/error" android:scheme="com.my.demo.app" /> </intent-filter> </activity>

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 the ConnectRequestErrorHandler.ConnectRequestCallback<Void>.

1 2 3 4 5 6 7 8 public ConnectRequestErrorHandler.ConnectRequestCallback<Void> bankConsentDeleteListener = new ConnectRequestErrorHandler.ConnectRequestCallback<Void>() { @Override public void success(Response<Void> response) { } ... }

Required parameters:

userTokenUser Token obtained from authorization endpoint.
bankSlugSlug for the bank user has selected from the list of banks
bankConsentDeleteListenerConnectRequestCallback<Void>
1 fsClient.deleteBankConsent(userToken, bankSlug, bankConsentDeleteListener );

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)