# 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-issuing-and-core-banking/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 |
**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. |
**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. |
[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... |
**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-issuing-and-core-banking/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-issuing-and-core-banking/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 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. |
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 |
**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 bank | Elixir | SEPA | SWIFT |
ZEN | Not available | Available | Not available |
Pekao | Available | Available | Available |