Overview

This document provides high level description of functionalities offered by IBAN Management Service. Solution allows to generate IBAN as a subaction for 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 our backend. Detailed information about the integration is available in the Technical documentation chapter.

Note: IBAN generating is available to entities registered as payment institutions or banks. If you are not such an institution, you are required to sign an agreement with our partner Quicko, who will generate IBAN numbers on your behalf.

Note: IBAN is the balance reference. Therefore, you must first create a balance to which a given IBAN will be generated. To create a balance for yourself and your users, use our balance management service - Antaca API. Every IBAN is created in response to the created 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.

Application components

This chapter describes IBAN Management as a complete solution divided into all components that support and are required to managing IBAN domain. 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 our side.

IBAN Management Service architecture diagram

IBAN Management API

Backend component that allows you to generate 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 API. In addition, IBAN Management API is responsible for validating each transfer order.

Supporting services

The following services are not a direct implementation part of the IBAN Management API. However, they are involved in the processes of creating and issuing IBAN numbers. Additionally they are allowing to perform money transfer process and saving such transfers history.

Antaca API

Backend component that is responsible for creating every balance in our system. After creating the balance, Antaca API sends an event which is catched by IBAN Management API. On the basis of this event the IMS API 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.

Transaction History Core

Backend component responsible for storing details of the performed transactions. Transaction information stored in this service is provided, among others, to the Admin Panel so that allow you to track transactions made by your users. Transactions stored in Transaction History Core are also transferred to the users as a history of debits and account top-ups. Eventually Transaction History Core is also able to send transaction notifications to you and and to you users.

Admin Panel

Component that allows to create a management panel thus allowing you to track every transfer performed by you users. Information shown in such panel will tell you, for example, whether various transactions are succeed or failed or what amount and currency was chosen for them. Additionally you are able to order an IBAN transfer by yourself using proper section in Admin Panel.

Note: Admin Panel is an optional service intended for customers who want to have greater control over transactions performed in their context.

Application details

The IBAN Management solution allows you to order and receive transfers of various types depending on the Bank that processes the ordered transfer. The choice of Bank is determined based on the IBAN structure, which contains information about which bank a given account comes from. The transfer type is, in turn, determined based on the transfer currency and the country from and/or to which the funds are going. This chapter will describe at a high level the methods of integration, the differences between banks along with supported transfer types and the assumptions defining the types of transfers.

Domain	Description
IBAN generating	Domain of the solution responsible for generating IBANs using a special algorithm based on the IBAN prefix that Customer received from the Payment Institution.
IBAN transfer receiving	Domain 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	Domain of the solution responsible for handling outgoing transfers and thus for initiating the sender's balance charging process.

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 for the Customers who want to connect to the IBAN Management service via mobile applications. In this solution, the Customer authorizes himself using session token previously obtained from the Mobile DC service.
REST API	Server-to-server integration has been for the 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.

Mobile SDK

The Mobile SDK implementation model was created for Customers who want to share the IBAN Management Service solution through their mobile application. After connecting the appropriate libraries provided by the SDK, your end users will be able to display their IBANs assigned to their balances and order transfers to potential recipients. These actions require authorization with a bearer session token from Mobile DC. Obtaining a valid Mobile DC token takes place after positive end user authorization. The mobile SDK is then responsible for communication with the proper Verestro server methods.

@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant "User" as user
participant "Customer App" as issuer
participant "Mobile DC" as mdc
participant "IBAN Management" as ims
note right of user: User opens Customer application
user->issuer: Login to app
issuer->mdc: Authenticate user
issuer<-mdc: Success
user<-issuer: Login successful
user->issuer: Check my IBAN
issuer->ims: Get user IBANs
ims->ims: Validate user
issuer<-ims: Return user's IBAN
user<-issuer: Display IBAN to the user
user->issuer: Perform money transfer
note right of user: User provides receiver's IBAN in Customer App
issuer->ims: Send funds on provided receiver IBAN
ims->ims: Order transfer
issuer<-ims: OK - Transfer ordered
user<-issuer: Transfer ordered
@enduml

REST API

The REST API implementation model was created for Customers who want to share the IBAN Management Service solution through server-to-server communication. After integration with the appropriate methods issued by IBAN Management Service your end users will be able to display their IBANs assigned to their balances and order transfers to potential recipients. In this model, communication is carried out with accordance to the REST protocol - each action is reflected in a specific API method to which you must integrate. Customer authorization is performed by checking the signature in the x509 certificate, which was generated in the context of your Customer account during the onboarding process. REST methods provided by IBAN Management Service are described in the Technical documentation chapter.

@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant "User" as user
participant "Customer App" as issuer
participant "IBAN Management" as ims
note right of user: In this case user authentication is Customers responsibility
user->issuer: Authenticate user
user<-issuer: Authentication success
user->issuer: Check my IBAN
issuer->ims: Get user IBANs
issuer-->ims: Provide x509 certificate
ims->ims: Validate certificate signature
issuer<-ims: Return user's IBAN
user<-issuer: Display IBAN to the user
user->issuer: Perform money transfer
note right of user: User provides receiver IBAN in Customer App
issuer->ims: Send funds on provided receivers IBAN
ims->ims: Order transfer
issuer<-ims: OK - Transfer ordered
user<-issuer: Transfer ordered
@enduml

IBAN generating

The process of generating IBANs can be divided into two stages. The first is to open an account with a payment institution - in this case it is Quicko. After opened an account you will receive an IBAN prefix, which allow to generate IBAN numbers for your users. The IBAN prefix is assigned to your account in the Verestro system during configuration and its editable. Each IBAN prefix is created in the context of a given currency, for example, if you want to have an account in PLN and USD, two prefixes will be assigned to your Customer account.

The second stage is to create a balance using the Antaca API service. IBANs are generated in response to the event of creating a balance for a given user and are a kind of identifier of a given balance. Depending on the implementation model, you can create user balances through our mobile SDK or REST commands. At this stage of integration, you should have already created a master balance account on the Antaca website. You can find more detailed information about balance creation in balance management service.

@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant "Enduser" as user
participant "Customer App" as issuer
participant "IBAN Management" 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
note right of issuer: At this point KYC process takes place
antaca->antaca: Create balance
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 - IBAN prefix. Based on this number we will generate bank account numbers for every user in your context.
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 funds

After creating a balance and generating an IBAN number, you can perform funds transfer operations. Funds can be transferred in two directions: sending funds to the recipient's IBAN and receiving funds on the balance using the IBAN assigned to it.
Depending on the IBAN origin and the country from which the account of the sender and recipient of funds comes from, the transfer may be sent as a internal, domestic, SEPA or SWIFT transfer. Depending on the transfer path, the transfer time may vary. Additional fees may also apply.

Transfer type	Condition	Additional fees	Potential transfer time
Internal	The sender's IBAN and the recipient's IBAN indicate the Antaca balance.	No	Instant
ELIXIR	The IBAN currency of the recipient and sender must be PL. The funds must be in Polish zloty.	No	Max 1 day Can be instant
SEPA	The IBAN currency of the recipient and sender must be the currency of a European country. The sender's and recipient's banks must support the SEPA system, otherwise the transfer will be made via SWIFT.	Possible occurrence	Max 1 day Can not be instant
SWIFT	Global transfer. The recipient's or sender's IBAN does not have the currency of a European country or the bank of one of the parties does not support the SEPA system.	Possible occurrence	Max 5 days Can not be instant
SORBNET	Polish system of high-value domestic transfers. Used mainly for quick transfers of high amounts between banks. Funds are usually transferred in real time or on the same day.	Possible occurrence	Max 1 day Can not be instant

Integrated Banks

Our cooperation with the payment institution, allowed us to open integration with below listed banks. This allows us to make transfers ordered by your end users who have an account generated in Antaca. The list of integrated banks is growing regularly and we invite banking partners to such cooperation. Contact us in case you want to cooperate with us in IBAN offering.

Integrated bank	Domestic	SEPA	SWIFT
ZEN	Not available	Available	Not available
Pekao S.A.	Available	Available	Available