IBAN Management SDK

Version 1.0.3

Table of Contents

  1. 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

  2. Technical overview

    2.1. Basic information

    2.2. Basic configuration

    2.3. IBAN Management SDK Setup

    2.4. Error handling

  3. IBAN Management Service

    3.1. getAccountIbans

  4. Document changelog

    4.1 Version 1.0.0

    4.2 Version 1.0.1

    4.3 Version 1.0.2

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 )

Changes not breaking compatibility:

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:

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:

Method type:

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.upaid.pl/artifactory/libs-release-local/"
	}
}

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. Debug version is ended with appendix "-debug" in version name. Samples below.

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

    

  

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

For debugging purposes:

    

  

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

2.2.1 Source code obfuscation and optimization

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

    

  

    
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:

    

  

    
android.enableR8=true

2.3 IBAN Management SDK Setup

Available configuration methods:

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

    

  

    
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

    

  

    
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

4.2 Version 1.0.1

4.3 Version 1.0.2

4.4 Version 1.0.3