Skip to content

BANC-6900: bank connect session flow changes #234

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gSrikar merged 1 commit into from
Dec 2, 2025
Merged

BANC-6900: bank connect session flow changes #234

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions docs/.vuepress/config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,6 +256,36 @@ module.exports = {
{
title: 'Frontend Integration',
path: '/session-flow/submit-data-frontend.html',
children: [
{
title: 'JavaScript SDK',
path: '/session-flow/javascript.html'
},
{
title: 'Android SDK',
path: '/session-flow/android.html'
},
{
title: 'iOS SDK',
path: '/session-flow/ios.html'
},
{
title: 'React Native SDK',
path: '/session-flow/react-native.html'
},
{
title: 'Flutter SDK',
path: '/session-flow/flutter.html'
},
{
title: 'Cordova SDK',
path: '/session-flow/cordova.html'
},
{
title: 'Ionic/Capacitor SDK',
path: '/session-flow/ionic-capacitor.html'
},
]
},
{
title: 'Backend Integration',
Expand Down
97 changes: 65 additions & 32 deletions docs/session-flow/android.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# BankConnect: Android

The Android SDK helps user submits their bank statements via upload or net banking credentials in your Android application.

## Requirements
Expand Down Expand Up @@ -70,7 +71,7 @@ dependencies {
</template>
</CodeSwitcher>

## Adding Dependency
## Add Dependency

In the project level `build.gradle` file or `settings.gradle`, add the repository URLs to all `allprojects` block or `repositories` block inside `dependencyResolutionManagement`.

Expand Down Expand Up @@ -132,38 +133,48 @@ implementation('in.finbox.bankconnect:hybrid:<BC_SDK_VERSION>:release@aar') {
</template>
</CodeSwitcher>


::: warning NOTE
Following will be shared by FinBox team at the time of integration:

- `ACCESS_KEY`
- `SECRET_KEY`
- `BC_SDK_VERSION`
- `CLIENT_API_KEY`
:::

## Integration Workflow

The diagram below illustrates the integration workflow in a nutshell:
<img src="/client_sdk.jpg" alt="Client SDK Workflow" />

## Sample Project

We have hosted a sample project on GitHub, you can check it out here:
<div class="button_holder">
<a class="download_button" target="_blank" href="https://github.com/finbox-in/bankconnect-android">Open GitHub Repository</a>
</div>

## Build Bank Connect
Build the `FinBoxBankConnect` object by passing `apiKey`, `linkId`, `fromDate`, `toDate` and `bank`.

Build the `FinBoxBankConnect` object by passing `apiKey`, `linkId`, `fromDate`, `toDate`, `bank`, `mode` and others.

<CodeSwitcher :languages="{kotlin:'Kotlin',java:'Java'}">
<template v-slot:kotlin>

```kotlin
FinBoxBankConnect.Builder(applicationContext)
.apiKey("CLIENT_API_KEY")
.linkId("your_link_id")
.fromDate("01/01/2021") // Optional: Default 6 months old date
.toDate("01/04/2021") // Optional: Default value 1 day less than current date
.bank("sbi") // Optional
.linkId("LINK_ID")
.fromDate("01/01/2021") // Optional: Default 6 months old date
.toDate("01/04/2021") // Optional: Default value 1 day less than current date
.bank("sbi") // Optional: Short code of the bank
.mode(PDF) // Optional: PDF Mode
.mobileNumber("9876543210") // Optional: Mobile number
.journeyMode(MULTI_PDF) // Optional: Multi PDF journey
.aaJourneyMode(ONLY_RECURRING) // Optional: Recurring AA pulls
.aaRecurringTenureMonthCount(3) // Optional: Consent duration is valid for 3 months
.aaRecurringFrequencyUnit(TimeUnit.DAYS) // Optional: Frequency value is in Days
.aaRecurringFrequencyValue(2) // Optional: Number of times to pull the data
.build()
```

Expand All @@ -172,31 +183,45 @@ FinBoxBankConnect.Builder(applicationContext)

```java
new FinBoxBankConnect.Builder(getApplicationContext())
.apiKey("your_api_key")
.linkId("your_link_id")
.fromDate("01/01/2021") // Optional: Default 6 months old date
.toDate("01/04/2021") // Optional: Default value 1 day less than current date
.bank("sbi") // Optional
.apiKey("CLIENT_API_KEY")
.linkId("LINK_ID")
.fromDate("01/01/2021") // Optional: Default 6 months old date
.toDate("01/04/2021") // Optional: Default value 1 day less than current date
.bank("sbi") // Optional: Short code of the bank
.mode(PDF) // Optional: PDF Mode
.mobileNumber("9876543210") // Optional: Mobile number
.journeyMode(MULTI_PDF) // Optional: Multi PDF journey
.aaJourneyMode(ONLY_RECURRING) // Optional: Recurring AA pulls
.aaRecurringTenureMonthCount(3) // Optional: Consent duration is valid for 3 months
.aaRecurringFrequencyUnit(TimeUnit.DAYS) // Optional: Frequency value is in Days
.aaRecurringFrequencyValue(2) // Optional: Number of times to pull the data
.build();
```

</template>
</CodeSwitcher>


| Builder Property | Description | Required |
| - | - | - |
| `apiKey` | specifies the `api_key` | Yes |
| `linkId` | specifies the `link_id` | Yes |
| `fromDate` | specifies the starting period of the statement in `DD/MM/YYYY`format | No |
| `toDate` | specifies the end period of the statement in `DD/MM/YYYY` format | No |
| `bank` | pass the [bank identifier](/bank-connect/appendix.html#bank-identifiers) to skip the bank selection screen and directly open a that bank's screen instead | No |
| `mode` | set the mode as pdf (manual upload) or aa (Account Aggregator) or online (Net Banking) | No |
| `mobile_number` | Prefills phone number in Account Aggregator mode | No |
| `journey_mode` | Optional parameter to set the journey (i.e.multi_pdf or multi_banking) | No |
| `aa_journey_mode` | set the journey mode for AA (i.e only_once or only_recurring) | No |
| `aa_recurring_tenure_month_count` | set the recurring consent duration (min: 1 and max: 24) | No |
| `aa_recurring_frequency_unit` | set the frequency unit to pull the data during the recurring consent duration (year, month, day, hour) | No |
| `aa_recurring_frequency_value` | set the frequency value to pull the data during the recurring consent duration (min: 1 and max: 3) | No |

`fromDate` and `toDate` specify the period for which the statements will be fetched. For example, if you need the last 6 months of statements, `fromDate` will be today's date - 6 months and `toDate` will be today's date - 1 day. If not provided the default date range is 6 months from the current date. It should be in `DD/MM/YYYY` format.

Once the above statement is added, a series of checks are done to make sure the SDK is implemented correctly. A `RunTimeException` will be thrown while trying to build the project in case any of the checks are not completed.

::: warning Minimal Requirements for SDK to work:

1. `apiKey` is is mandatory
2. `linkId` is mandatory, and should be at least 8 characters long
3. In case `fromDate` / `toDate` is provided, make sure they are of correct date format: `DD/MM/YYYY`.
Expand All @@ -206,7 +231,8 @@ Once all these conditions are met, the BankConnect object will build.
:::

## Show SDK Screen
Start BankActivity and listten for the result

Start BankActivity and listen for the result

<CodeSwitcher :languages="{kotlin:'Kotlin',java:'Java'}">
<template v-slot:kotlin>
Expand Down Expand Up @@ -246,11 +272,14 @@ result.launch(new Intent(this, BankActivity.class));
</CodeSwitcher>

## Parse Results
Once the user navigates through the banks and uploads the bank statement, the sdk automatically closes `BankActivity` and returns `FinboxOnSuccessPayload`.

`FinboxOnSuccessPayload` contains `linkId` and `entityId`. A successful upload contains a unique `entityId`.
* linkId - Unique id passed when building the Bank Connect object
* entityId - Unique id of a successful statement upload
Once the user navigates through the banks and uploads the bank statement, the sdk automatically closes `BankActivity` and returns `FinBoxPayload`.

`FinBoxPayload` contains `linkId` and `entityId` (or `sessionId`). A successful upload contains a unique `entityId` (or `sessionId`).

- linkId - Unique id passed when building the Bank Connect object
- entityId - Unique id of a successful statement upload during Entity flow
- sessionId - Session id of a successful statement upload during Session flow

<CodeSwitcher :languages="{kotlin:'Kotlin',java:'Java'}">
<template v-slot:kotlin>
Expand All @@ -261,18 +290,19 @@ if (result?.resultCode == Activity.RESULT_OK) {
// Read extras
val extras = result.data?.extras
// Read success payload
val payload = extras?.getParcelable<FinboxOnSuccessPayload>(
FinboxBankConstants.BUNDLE_EXTRA_SUCCESS_PAYLOAD
)
val payload = extras?.getParcelable<FinBoxPayload>(FINBOX_JOURNEY_RESULT)
when {
payload == null -> {
// Failed to Receive Payload
}
payload.entityId.isNullOrBlank() -> {
// Failed to Upload Document
payload.entityId.isNullOrBlank() && payload.sessionId.isNullOrBlank() -> {
// Failed to Upload Document during Entity flow or
// Failed to Upload Document for Session Flow
}
else -> {
// Upload Success
// Read the session id for session flow or
// Read the entity id
}
}
} else {
Expand All @@ -290,14 +320,16 @@ if (result != null && result.getResultCode() == Activity.RESULT_OK) {
@Nullable final Bundle extras = result.getData() != null ? result.getData().getExtras() : null;
if (extras != null) {
// Read success payload
@Nullable final FinboxOnSuccessPayload payload =
extras.getParcelable(FinboxBankConstants.BUNDLE_EXTRA_SUCCESS_PAYLOAD);
@Nullable final FinBoxPayload payload = extras.getParcelable(FINBOX_JOURNEY_RESULT);
if (payload == null) {
// Failed to Receive Payload
} else if (payload.getEntityId() == null || payload.getEntityId().length() == 0) {
// Failed to Upload Document
} else if ((payload.getEntityId() == null || payload.getEntityId().length() == 0) && (payload.getSessionId() == null || payload.getSessionId().length() == 0)) {
// Failed to Upload Document during Entity flow or
// Failed to Upload Document for Session Flow
} else {
// Upload Success
// Read the session id for session flow or
// Read the entity id
}
} else {
// Failed to Receive data
Expand All @@ -310,29 +342,30 @@ if (result != null && result.getResultCode() == Activity.RESULT_OK) {
</template>
</CodeSwitcher>


:::warning Webhook
To track detailed errors, and transaction process completion at the server-side, it is recommended to also integrate [Webhook](/bank-connect/webhook.html).
:::

## Customization

`BankActivity` inherits the themes and color from Material Dark Action Bar Theme. Most of the case, there would be less customization requried but if there is a mismatch in colors, you can customize it through your `styles.xml` file.

1. The sdk Toolbar color uses `colorPrimary`. If your app toolbar color is different from `colorPrimary` then change the color by updating the background color
```xml

```xml
<style name="BankConnectTheme.Toolbar">
<item name="android:background">@color/colorWhite</item>
</style>
```
```

2. `BankConnectTheme` is the base theme of the sdk and it inherits `Theme.MaterialComponents.Light.DarkActionBar`. If your app doesn't inherit Dark Action Bar theme then you can change the sdk theme to inherit your app base theme.

```xml
```xml
<style name="BankConnectTheme" parent="AppTheme">

</style>

<style name="BankConnectTheme.AppBarOverlay" parent="AppTheme.AppBarOverlay" />

<style name="BankConnectTheme.PopupOverLay" parent="AppTheme.PopupOverlay" />
```
```
Loading