Android Build UX SDK

Introduction

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

Requirements

  1. Install or update Android Studio to version 3.2 or greater
  2. We support Android 5.0 and greater

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' } } }

Planky 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 Planky 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.2.0' }

Integrating with Planky

You can select which environment you want to use the Planky 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

1. Get User token

A user token can be created for the user using the customer_id. A customer_id is available after creating the user Create Customer

You must then use the customer_id to create user_token Create User Token

2. Create the Planky Client

Choose the environment you want to integrate.

1 2 3 4 5 6 7 /** * @param environment */ Environment environment = Environment.SANDBOX final FriendlyScoreClient fsClient = new FriendlyScoreClient(environment);

The fsClient will be required to make other requests

3. 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 your server
listOfBanksListenerConnectRequestErrorHandler.ConnectRequestCallback<List>

Use the Planky Client 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.

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 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 your server
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 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.

5. 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 your server
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.
redirectUriThis must be the scheme you are using to bring the user back to your app. It must be the same as set in the Planky developer console and AndroidManifest.xml while declaring the activity.
bankFlowUrlListenerConnectRequestErrorHandler.ConnectRequestCallback
1 2 3 4 5 6 7 8 9 10 11 let redirectUriValue: String = "YOUR_APP_REDIRECT_SCHEME" var userToken: String = "User Token obtained from your server" fsClient?.fetchBankFlowUrl(userToken: userToken, slug: bankSlug, transactionFromTimeStampInSec: dateFrom, transactionToTimeStampInSec: dateTo, redirectUri: redirectUriValue, 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.

6. Redirect back to the app

Go to the Redirects section of the Planky 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 Planky 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>

7. 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 your server
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.

42 Brook Street, Mayfair

London W1K 5DB

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: 821100, 781963)