IBAN Management SDK

Version 1.0.11

IBAN Management SDK Overview

1.1. What is IBAN Management SDK?

1.2. How does IBAN Management SDK work?

1.3. Versioning and backward compatibility
Technical overview

2.1. Basic information

2.2. Basic configuration

2.3. IBAN Management SDK Setup

2.4. Error handling
IBAN Management Service

3.1. getAccountIbans
Document changelog

4.1 Version 1.0.0

4.2 Version 1.0.1

4.3 Version 1.0.2

4.4 Version 1.0.3

4.5 Version 1.0.4

4.6 Version 1.0.5

4.7 Version 1.0.6

4.8 Version 1.0.7

4.9 Version 1.0.8

4.10 Version 1.0.9

4.11 Version 1.0.10

4.12 Version 1.0.11

IBAN Management SDK Overview

1.1 What is IBAN Management SDK?

IBAN Management SDK was created for Customers who want to provide their end users the possibility to
receive money on IBAN (bank account number).
This solution allows Customer's users to reload their balances via a bank transfer.

1.2 How does IBAN Management SDK work?

IBAN Management SDK requires Mobile DC as a dependency.
It’s required for the IBAN Management SDK to work correctly to handle user's session and other data.
Please read the Mobile DC SDK’s documentation to see more details about the installation and
integration process.

In order to incorporate this SDK into your app, see Basic configuration

1.3 Versioning and backward compatibility

SDK is based on semantic versioning.For example: 1.0.0 ( MAJOR.MINOR.PATCH )

Major version compatibility-breaking changes in SDK public APIs.
It is mandatory to update application code, to use SDK, when this is incremented.
Minor version tracks new, not compatibility-breaking changes in public API of SDK.
It is optional to update application code, when this digit is incremented.
Patch version tracks internal changes in SDK.
No updates in application code are necessary to update to version, which has this number
incremented.

Changes not breaking compatibility:

adding new optional interface to SDK setup
adding new method to any domain
adding new enum value to input or output
adding new field in input or output model

2. Technical overview

2.1. Basic information

2.1.1 Facade

Facade is an entry point to communication with IBAN Management SDK.

2.1.2 Multiple facade types

IBAN Management SDK provides two public API's with same functionalities, the API's are:

IbanManagementCoroutineService for projects which uses Kotlin programming language and
Coroutines.
IbanManagementStdService for projects which uses Kotlin or Java programming language and
standard Callback.

The difference between the API's is a way of providing data to SDK methods and getting the results
from them.
Input and output as an data models are the same.
This documentation presents I/O types in a Kotlin way as it's easier to mark nullable fields (as
question mark).

2.1.3 Method structure

Every method description has same structure.

Execution type:

Asynchronous - operation could take more time and method is called on thread different than
main. The result of execution is provided in callback (described below).
Synchronous - result of operation is provided as method return type.

Method type:

Online - operation requires Internet connection.
Offline - operation can be called without Internet connection.

Input
Input parameters with name, type and description.

Output
Result delivered by standard Callback with data or result is suspended until the Coroutine
completes <Multiple facade types>.

2.2 Basic configuration

2.2.1 Min SDK Version

The minSdkVersion must be at least 23 (Android 6.0).

2.2.2 Artifactory

SDK is available on Verestro maven repository and can be configured in project using Gradle build
system.

Username and password are provided by Verestro.

repositories {    
    maven {   
       credentials {   
          username "<enter_username_here>"   
          password "<enter_password_here>"   
       }   
       url "https://artifactory.verestro.com/artifactory/android-release/"  
    }}  ```  

#### 2.2.3 SDKs version  

IBAN Management SDK is available in two versions: debug and release.  
The difference between version is debug allows to use application with debugger connected.  
Samples below.  

For release version, used on production environment in application uploaded to Google Play:  

```gradle  
dependencies {    
    implementation 'pl.upaid.module:mobiledc:{version}'  
    implementation 'com.verestro.sdk:ibans:${version}'}  ```  

For debugging purposes:  

```gradle  
dependencies {    
    implementation 'pl.upaid.module:mobiledc:{version}-debug'  
    implementation 'com.verestro.sdk:ibans:debug-${version}'}  ```  

#### 2.2.1 Source code obfuscation and optimization  

As SDK is written in Kotlin language we recommend to add following code to gradle configuration:  

```gradle  
android {  ...   
     kotlinOptions {   
        freeCompilerArgs = [   
           '-Xno-param-assertions',   
           '-Xno-call-assertions',   
           '-Xno-receiver-assertions'   
       ]   
    }    
packagingOptions { exclude '/kotlin_metadata/**' } ...  
}  ```  

Then use newest tools for code shrinking, optimization and obfuscation from Google by enabling R8  
instead Proguard in gradle.properties file:  

```gradle  
android.enableR8=true  ```  

### 2.3 IBAN Management SDK Setup  

Available configuration methods:  

- IbanManagementCoroutineApi.init(configuration: Configuration)  
- IbanManagementStdApi.init(configuration: Configuration)  

#### 2.3.1 Input  

**`Configuration`**  

| Parameter     | Type          | Description         |  
|---------------|---------------|---------------------|  
| configuration | Configuration | Configuration model |  

**`Configuration`**  

| Parameter         | Type          | Description             |  
|-------------------|---------------|-------------------------|  
| productName       | String        | API product name        |  
| url               | String        | API hostname URL        |  
| certificateHashes | List\<String> | API hostname Pin SHA256 |  

#### 2.3.2 Sample  

**`IbanManagementCoroutineApi`**  

```kotlin  
fun init(configuration: Configuration) {    
    IbanManagementCoroutineApi.init(configuration)  
}

IbanManagementStdApi

fun init(configuration: Configuration) {    
    IbanManagementStdApi.init(configuration)  
}

2.4 Error handling

SDK returns errors by IbansSdkException, which could be catched by application and shown on UI with
detailed message.

Table below describes general exception types.

Exception type	Exception class	Description
Backend	IbansSdkException	Provides additional validation or error on backend side. Application should get reason code and show suitable message or made action. Message should be never shown to user. Could be logged for error reporting and for developers. List of available exceptions in table below

IbansSdkException

Exception	Parameters	Description
HttpApiException	code: Int, message: String?	HTTP API exception.
TechnicalException	message: String?	Technical exception.
UnknownErrorStatusException	status: String?	An unknown error occurred.
NoSessionException		User is unauthorized - session expired.
RequestCancelledException		Request was canceled.
NoCertificatePinningException		No certificate pinning.
IssuerNotFoundException		Issuer not found.
InvalidConfigurationException		Invalid configuration
InternalServerErrorException		Internal server error

3 IBAN Management Service

3.1 getAccountIbans

Asynchronous. Online.    

Provide account ibans from backend.  
Functionality to receive funds on available IBAN number by any banking transfer. ```  

#### 3.1.1 Input  

**`GetAccountIbansData`**  

| Parameter           | Type                | Description                  |  
|---------------------|---------------------|------------------------------|  
| getAccountIbansData | GetAccountIbansData | Get account ibans data model |  

**`GetAccountIbansData`**  

| Parameter | Type   | Description        |  
|-----------|--------|--------------------|  
| balanceId | String | Balance identifier |  

#### 3.1.2 Output  

##### 3.1.2.1 Success

Success callback with GetAccountIbansResult model.

**`GetAccountIbansResult`**  

| Parameter             | Type                  | Description                    |  
|-----------------------|-----------------------|--------------------------------|  
| getAccountIbansResult | GetAccountIbansResult | Get account ibans result model |  

**`GetAccountIbansResult`**  

| Parameter    | Type                    | Description   |  
|--------------|-------------------------|---------------|  
| accountIbans | List\<AccountIbanModel> | List of ibans |  

**`AccountIbanModel`**  

| Parameter | Type   | Description                       |  
|-----------|--------|-----------------------------------|  
| balanceId | String | Unique identifier of balance      |  
| iban      | String | International bank account number |  
| currency  | String | Three letters code in ISO 4217    |  

##### 3.1.2.2 Failure

Failure callback with throwable.

#### Sample  

**`Standard Callback`**  

```kotlin  
fun getAccountIbans(getAccountIbansData: GetAccountIbansData) {  
    IbanManagementStdApi        .ibanManagementStdService        .getAccountIbans(            getAccountIbansData = getAccountIbansData,            callback = object : ApiCallback<GetAccountIbansResult> {                override fun onSuccess(response: GetAccountIbansResult) {                    // handle success                }                override fun onFailure(error: Throwable) {                    // handle error                }            }        )}

Kotlin Coroutines

suspend fun getAccountIbans(getAccountIbansData: GetAccountIbansData): GetAccountIbansResult =  
    IbanManagementCoroutineApi        .ibanManagementCoroutineService    
        .getAccountIbans(getAccountIbansData = getAccountIbansData) ```  

## 4. Document changelog

### 4.1. Version 1.0.0

- Created IBAN Management SDK.  

### 4.2 Version 1.0.1

- Refactored Configuration model.  
- Added certificate pinning.  

### 4.3 Version 1.0.2

- Added hostname verification.  

### 4.4 Version 1.0.3

- Disabled pinning and obfuscation for debug.  

### 4.5 Version 1.0.4

- Updated koin to version 3.5.3.  
- Updated java to 17.  
- Updated compile and target android version.  

### 4.6 Version 1.0.5

- Improved SDKs deploying.  

### 4.7 Version 1.0.6

- Internal changes have been introduced to improve build process.  

### 4.8 Version 1.0.7

- Update koin to version 4.0.4  
- Update java to 21  
- Update compile and target android version  

### 4.9 Version 1.0.8

- Internal changes improving SDK delivery process.  

### 4.10 Version 1.0.9

- Internal. Updates build utilities.  

### 4.11 Version 1.0.10

- Internal changes improving SDK.  

### 4.12 Version 1.0.11

- Internal changes. Updated supported token handling.

IBAN Management SDK

Table of Contents