# 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](https://developer.verestro.com/books/iban-management-refactor/page/technical-documentation) chapter.

**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](https://developer.verestro.com/books/card-management-system/page/overview#bkmrk-user-balance) - 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/CP Admin Panel/Corporate 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.](https://developer.verestro.com/books/iban-management/page/overview#bkmrk-iban-structure)
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.
Master account This is the account number assigned to the Customer in the bank's system. The total funds in each Master Customer account is the amount that the Customer has in his Master Balance.
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.](https://developer.verestro.com/books/iban-management/page/overview#bkmrk-iban-structure)
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](https://developer.verestro.com/books/iban-management/page/overview#bkmrk-supported-currencies).
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 additional work on your part as a Customer. Processes such as transaction validation, debiting and topping up balances or saving transaction history per end user are performed on our side. [![IMS architecture.drawio.png](https://developer.verestro.com/uploads/images/gallery/2024-12/scaled-1680-/IY2ims-architecture-drawio.png)](https://developer.verestro.com/uploads/images/gallery/2024-12/IY2ims-architecture-drawio.png) ### IBAN Management API Backend component that allows you to generate IBANs for your end users. It is also responsible for handling debits and credits of a given balance if the operation performed on the balance is a part of the IBAN transfer. To do so this service communicates directly with [Antaca API](https://developer.verestro.com/books/card-management-system/page/overview#bkmrk-user-balance). In addition, IBAN Management API is responsible for validating each transfer order and communicating with proper bank. ### 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](https://developer.verestro.com/books/card-management-system/page/overview#bkmrk-user-balance) 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](https://developer.verestro.com/books/card-management-system/page/overview#bkmrk-user-balance). #### 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](https://developer.verestro.com/books/transaction-history-api/page/technical-documentation-thc-external-api) are also transferred to the users as a history of debits and account top-ups. Eventually [Transaction History Core](https://developer.verestro.com/books/transaction-history-api/page/technical-documentation-thc-external-api) is also able to send transaction notifications to you and and to you users. #### Admin Panel/Corporate 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. You can also track the available funds of each of your registered master accounts. Additionally you are able to order an IBAN transfer by yourself using proper section in [Admin Panel.](https://developer.verestro.com/books/administration-panel/page/technical-documentation-api)

**Note:** [Admin Panel](https://developer.verestro.com/books/administration-panel/page/technical-documentation-api) 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](https://developer.verestro.com/books/iban-management-refactor/page/overview#bkmrk-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](https://developer.verestro.com/books/iban-management-refactor/page/use-cases#bkmrk-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](https://developer.verestro.com/books/iban-management-refactor/page/use-cases#bkmrk-iban-transfer-sendin)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](https://developer.verestro.com/books/iban-management-refactor/page/overview#bkmrk-mobile-sdk-integrati-0) and [REST API](https://developer.verestro.com/books/iban-management-refactor/page/overview#bkmrk-rest-api-integration). 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.
[REST API](https://developer.verestro.com/books/iban-management-refactor/page/overview#bkmrk-rest-api-integration)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](https://developer.verestro.com/books/iban-management/page/technical-documentation#bkmrk-how-to-generate-csr-). Details of integration via REST API are available in the [Technical documentation chapter](https://developer.verestro.com/books/iban-management/page/technical-documentation).
[Mobile SDK](https://developer.verestro.com/books/iban-management-refactor/page/overview#bkmrk-mobile-sdk-integrati-0)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](https://developer.verestro.com/books/white-label-application/page/overview#bkmrk-1.3.1-mdc) service.

**Important!** Implementation is work in progress...

#### 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](https://developer.verestro.com/books/iban-management/page/technical-documentation#bkmrk-how-to-generate-csr-), 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](https://developer.verestro.com/books/iban-management-refactor/page/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 "Verestro" 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 #### 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](https://developer.verestro.com/books/white-label-application/page/overview#bkmrk-1.3.1-mdc). Obtaining a valid [Mobile DC](https://developer.verestro.com/books/white-label-application/page/overview#bkmrk-1.3.1-mdc) token takes place after positive end user authorization. The mobile SDK is then responsible for communication with the proper Verestro server methods.

**Important!** Implementation is work in progress...

### IBAN generating The process of generating IBANs can be divided into two stages. The first is to open an master account with a payment institution - contact our Sales department or our Project Manager assigned to you to know more. After opened an master account you will receive an IBAN prefix, which allow to generate account numbers for your end users and associate these end users with your integration. 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 a master account in PLN and USD then two prefixes will be assigned to your Customer account in our system. The second stage is to create a balance using the [Antaca API](https://developer.verestro.com/books/card-management-system/page/overview#bkmrk-user-balance) 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. Alternatively, we can not generate an IBAN in response to the creation of a balance and leave this logic on your side (we provide an appropriate API method that allows you to create an IBAN in the context of a given balance). Depending on the implementation model, you can create user balances through our mobile SDK or REST commands.

**Note:** Only one bank account number can be assigned to one balance.

**Note:** At this stage of integration, you should have already created a master balance in the Antaca service. You can find more detailed information about balance creation in [balance management service](https://developer.verestro.com/books/card-management-system/page/overview#bkmrk-user-balance).

@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 123456782 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.
909090909090909016 digits tracking a specific account.
#### Supported currencies
PLNPolish zloty
EUREuro
USDAmerican dollar
GBPBritish pound sterling
CHFSwiss franc
AUDAustralian dollar
CADCanadian dollar
CZKCzech koruna
DKKDanish krone
NOKNorwegian krone
SEKSwedish krone
HUFHungarian forint
JPYJapanese yen
MXNMexican peso
ZARSouth african rand
TRYTurkish lira
BGNBulgarian lev
RONomanian leu
CNYChinese yuan
THBThai baht
ILSIsraeli new shekel
HKDHong 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, elixir, SEPA or SWIFT transfer. Depending on the transfer path, the transfer time may vary. Additional fees may also apply.

**Note: **In the case of transfers above one million, a SORBNET transfer is made.

**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 Elixir SEPA SWIFT
ZEN Not available Available Not available
Pekao Available Available Available