Overview

This document provides high level description of functionalities offered by IBAN Management Service. Solution allows to generate IBAN as a reaction to the created balance, thus enabling transfers using the IBAN number. The solution is very simple to integrate as 
most of the processes, such as handling transfers, are performed by the payment institution and the Verestro backend. Detailed information about the integration is available in the Technical documentation chapter.

To use the application the creation of the Customer account in the IBAN Management Service and integration with the Antaca service - which is responsible for generating balances - are required. More information about balance generating is available in the Antaca Create User Balance documentation. The IBAN is created in response to the created balance and is a kind of indicator for this balance.

Abbreviations

This section shortly describes abbreviations and acronyms used in the document.

Abbreviation	Description
SDK	Software Development Kit
API	Application Programming Interface
IBAN	International Bank Account Number
OS	Operative System
IMS	IBAN Management Service
THC	Transaction History Core
AP	Admin Panel

Terminology

This section explains a meaning of key terms and concepts used in this document.

Name	Description
IBAN	International bank account number, which is a standard international account number. IBAN consists of the: two-digit country code (ISO) two-digit control number account number IBAN length may be different depending to country. More detailed information about IBAN can be find in IBAN generating chapter.
Base IBAN / IBAN prefix	Base IBAN issued to the Customer by the IBAN Issuing Institution. Each base IBAN is issued per currency and is necessary to generate new IBANs in the context of each Customer.
Balance	Current amount that is in our bank account and is available for use at any time. Each transfer with an IBAN assigned to another account reduces the balance of our bank account. In turn, each top up on our account causes the account balance to increase.
Customer	Institution which is using Verestro products. Basically Customer can be called Verestro client.
IBAN Issuing Institution	Verestro partner who's assigning base IBANs to IMS Customers and settles IBAN transfers. This institution contacts with the Bank. This means that the responsibility for the settlement of the transaction is beyond the Customer. More detailed information about base IBAN can be find in IBAN generating chapter.
Bank	The Bank contacts the IBAN Issuing Institution informing about transfers that need to be settled.
Currency	Monetary unit - the name of the money used in a given country. This name is used primarily in the context of international exchange. To see the list of the supported currencies please visit Supported currencies chapter.
Transaction file	A file with the .pli extension containing information about bank transfers. On the basis of this file, balance transfers and debits are generated in response to transfers made using the IBAN number. These files are created by the Bank being a partner of Verestro and only IBAN Issuing Institution employees have access to them.

IBAN Management Service key components

This chapter describes IBAN Management as a complete solution divided into Verestro components that support and that are required to managing IBANs. Individual functionalities for which these services are responsible reduce the need for additional work on the part of the Customer to a minimum. Processes such as transaction validation, debiting and topping up balances or saving transaction history per enduser are performed on the Verestro side.

Component	Description
IBAN Management Service	Backend component that allows Customer to issue IBANs. It is also responsible for handling debits and credits of a given balance if the operation performed is an IBAN transfer. To do so this service communicates directly with Antaca. In addition, IMS is responsible for validating each transfer order.
Antaca	Backend component that is responsible for creating balances for Customers. After creating the balance, Antaca sends an event. On the basis of this event  the IMS creates an IBAN assigned to the created balance. It is a key component without which IBAN transfers are not possible. More information on Antaca balances can be found here.
Admin Panel	Web component that allows to create a panel for the Customer so that he can see his endusers' IBAN numbers (the IBAN number is not a sensitive value) and can track transactions performed by these IBAN's. Through the Admin Panel, transaction files are also uploaded. To see an sample view of the Panel and the user experience of the Admin Panel, please visit the Use Cases chapter.
Transaction History Core	Backend component responsible for storing details of the performed transactions. Transaction information stored in THC is provided, among others, to the Admin Panel so that allows the Customer to tracking transaction made by his endusers. Transactions stored in THC are also transferred to the enduser's as a history of debits and account top-ups. Eventually THC is also able to send transaction notifications to the Customer.

The diagram below shows each component involved in the IBAN Management Service processes and the dependencies between them:

Implementation models

Verestro provides two implementation models for the IBAN Management Solution - Mobile SDK and REST API. Public methods in IBAN Management were implemented for getting and displaying IBANs. This section provides the architecture information divided into components that are included in the process.

Mobile SDK

Integration via mobile SDK has been made available to Customers who want to connect to the IBAN Management service via mobile applications. In this solution, the Customer authorizes himself using a session token previously obtained from the Mobile DC service. Details of integration via mobile SDK are available in the Technical documentation chapter.

REST API

Server-to-server integration has been made available for Customers who want to connect to the IBAN Management website directly from their backend. This type of integration was created in accordance with the REST architectural pattern. In this solution, the Customer authorizes himself with a signed x509 certificate. Details of integration via REST API are available in the Technical documentation chapter.

IBAN Management Service details

The chapter describes what possibilities the IBAN Management Service offers and what are the most important processes of the solution.

IBAN generating	An element of the solution that is responsible for generating IBANs using a special algorithm based on the base IBAN that Customer received from the IBAN Issuing Institution.
IBAN transfer receiving	An element of the solution responsible for handling incoming transfers to the received IBAN and thus for initiating the process of topping up recipient's balance.
IBAN transfer sending	An element of the solution responsible for handling outgoing transfers and thus for initiating the sender's balance charging process.

IBAN generating

The IBAN generation process can be divided into two stages. Each of these stages is described in this chapter. The first and most important step is to delivery of the base IBAN to Verestro by the Customer. The base IBAN is generated by the IBAN Issuing Institution, which is a Verestro partner. After receiving the base IBAN, Verestro will assign it to the Customer's account. 
Based on the base IBAN, each subsequent IBAN in the context of the Customer will be created. This step is performed only once during the Onboarding process.

The second step is to create an Antaca balance which means that at this stage the Customer should already be integrated with the Antaca service. IBAN is an indicator of the balance, so without the created balance, the use of IBANs is not possible. The Customer integrated with Antaca service is able to provide its endusers with the ability to generate balances and thus creating IBANs assigned to these balances. Balance creation method is described in Antaca Create User Balance documentation.

The diagram below shows the creation of the new IBAN step by step.

@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #002060
skinparam noteBorderColor #002060
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #002060
ArrowFontColor #002060
ActorBorderColor #002060
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #002060
ParticipantBackgroundColor #002060
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #002060
LifeLineBorderColor #002060
}
participant "Endser" as user
participant "Customer App" as issuer
participant "IBAN Management Service" as ims
participant "Antaca" as antaca
note right of user: Enduser creates new balance
user->issuer: Create balance
issuer->antaca: Create balance for this enduser
ims<-antaca: New balance generated event
ims->ims: Create IBAN number for new balance
issuer<-antaca: Balance created
issuer->ims: Get enduser IBAN
issuer<-ims: Return IBAN number
user<-issuer: Display IBAN number
@enduml

IBAN structure

Each IBAN has a specific structure. For presentation purposes, e.g. on printouts, the IBAN number can be divided into 4-character groups separated by a space character. Depending on the country, the number of characters that make up the IBAN may vary. It is also worth mentioning that the IBAN consists of few fragments which are described below:

Two-letter country code according to the ISO-3166 standard (for Poland these are the letters PL).

Two-digit control number and the BBAN bank account number according to the system selected in a given country and a given bank. The BBAN account number can be of any length (up to 30 characters), but the length must be fixed for a given country.

The account number may contain numbers 0-9 and capital letters of the Latin alphabet A-Z.

Example: Polish IBAN numbers consist of 2 letters of the country and 26 digits according to the following division PL00123456789090909090909090.

PL	2 letters of the country.
00 12345678	2 digits of the checksum and 8 digits tracking a given bank and, for example, it's specific branch.
9090909090909090	16 digits tracking a specific account.

Supported currencies

PLN	Polish zloty
EUR	Euro
USD	American dollar
GBP	British pound sterling
CHF	Swiss franc
AUD	Australian dollar
CAD	Canadian dollar
CZK	Czech koruna
DKK	Danish krone
NOK	Norwegian krone
SEK	Swedish krone
HUF	Hungarian forint
JPY	Japanese yen
MXN	Mexican peso
ZAR	South african rand
TRY	Turkish lira
BGN	Bulgarian lev
RON	omanian leu
CNY	Chinese yuan
THB	Thai baht
ILS	Israeli new shekel
HKD	Hong Kong dollar

Transfer receiving

This functionality allows enduser to receive transfers. Endser which is using Customer's application is able to share his IBAN to potential payer. This type of transfer is a transaction that top ups enduser's balance. As receiving an incoming transfer requires only to provide IBAN to his potential payer, the only method with which the Customer must integrate is getIban or getIbanMobile - depending on the implementation model. For integration details please visit Technical documentation chapter.

Transfer sending

This functionality allows enduser to order outgoing transfers. Enduser which is using Customer's application is able to sends money on a given IBAN. The outgoing transfer is a transaction that charges enduser's balance.

Implementation work in progress...

Admin Panel

Using the Admin Panel service allows the Admin Panel operator to perform various actions related to IBAN transfers. Actions of this type include, among others, filtering endusers and their IBANs, tracking the history of enduser's transactions and their account balances, as well as execution of the ordered transfers. The operator of the Admin Panel is an employee of a given institution. Basicly it can be a person representing the Customer's institution or an employee of the IBAN Issuing Institution. Each of the operators has an assigned role in the Admin Panel, which determines what actions in the Admin Panel they can perform. For more detailed information please visit Admin Panel use cases chapter.

After creating an Admin Panel instance in the context of IBAN Management Service for a given Customer, remember to provide the domain of this instance. We need to add this domain to the whitelist. Otherwise, IBAN Management Service API will reject every request with HTTP status 403 - Forbidden.

Example domain to be provided for whitelisting: https://admin-panel-customername.verestro.com