Overview

This document provides a high-level description of the functionalities offered by the IBAN Management Service. The solution allows you to generate an IBAN as a sub-action for a created balance, thus enabling transfers using the IBAN number. The solution is simple to integrate, as most 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.

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. The IBAN length may vary depending on the country. More detailed information about the IBAN can be found in the IBAN generating chapter.
IBAN prefix	The part of the IBAN that identifies the bank or financial institution. It enables users to generate IBANs.
Balance	The current amount in the bank account that is available for use. Each outgoing transfer reduces the balance, and each top-up to the account increases the balance.
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	An institution using Verestro products. Essentially, a Customer can be referred to as a Verestro client.
IBAN Issuing Institution	Licensed financial entity that generates and manages IBANs on behalf of its partners, ensuring compliance and settlement with the connected bank.
Bank	Licensed financial institution that holds and manages customer funds, processes payments, and provides financial services
Currency	Monetary unit - the name of the money used in a particular country or economic region. To see the list of the supported currencies please visit Supported currencies chapter.

Application components

This chapter describes IBAN Management as a complete solution, divided into all the components that support and are required for managing the IBAN domain. The 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, and saving transaction history per end user are handled on our side.

IBAN Management API

A backend component that allows you to generate IBANs for your end users. It is also responsible for handling debits and credits on a given balance when the operation is part of an IBAN transfer. To perform these actions, the service communicates directly with Antaca API. Additionally, the IBAN Management API is responsible for validating each transfer order and communicating with the appropriate bank.

Supporting services

The following services are not a direct part of the IBAN Management API implementation. However, they are involved in the processes of creating and issuing IBAN numbers. Additionally, they enable the execution of money transfers and the storage of transfer history.

Antaca API

A backend component responsible for creating every balance in our system. After a balance is created, Antaca API sends an event that is captured by the IBAN Management API. Based on this event, the IMS API generates an IBAN assigned to the newly created balance. This is a key component without which IBAN transfers would not be possible. More information about Antaca balances can be found here.

Transaction History Core

A backend component responsible for storing details of performed transactions. The transaction data stored in this service is provided, among other things, to the Admin Panel, allowing you to track transactions made by your users. Transactions stored in the Transaction History Core  are also delivered to users as a history of debits and account top-ups. Additionally, Transaction History Core can send transaction notifications.

Admin Panel/Corporate Panel

A component that enables the creation of a management panel, allowing you to track every transfer made by your users. The information displayed in this panel will show you, for example, whether transactions were successful or failed, as well as the amount and currency used. You can also monitor the available funds of each of your registered master accounts. Additionally, you can initiate an IBAN transfer yourself using the appropriate section in the 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 send and receive various types of transfers, depending on the bank that processes the transfer. The choice of bank is determined by the structure of the IBAN, which indicates the bank from which the account originates. The type of transfer is determined by the currency of the transaction and the country from which the funds are sent and/or to which they are received.

This chapter provides a high-level overview of the integration methods, the differences between banks along with the supported transfer types, and the criteria that define each type of transfer.

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.

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	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. 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, 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 "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. 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.

Important! Implementation is work in progress...

IBAN generating

The process of generating IBANs can be divided into two stages. The first stage is opening a master account with a payment institution – contact our Sales department or your assigned Project Manager to learn more. Once a master account is opened, you will receive an IBAN prefix, which allows you to generate account numbers for your end users and associate these users with your integration. The IBAN prefix is assigned to your account in the Verestro system during configuration and is editable. Each IBAN prefix is created in the context of a specific currency. For example, if you want to have a master account in both PLN and USD, two prefixes will be assigned to your customer account in our system.

The second stage is to create a balance using the Antaca API service. IBANs are generated in response to the creation of a balance for a given user and serve as an identifier for that balance. Alternatively, we can skip IBAN generation at the moment of balance creation and leave this logic to your system (we provide an appropriate API method that allows you to generate an IBAN in the context of a specific balance). Depending on your implementation model, you can create user balances through our mobile SDK or via REST API calls.

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.

@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 after KYC
user->issuer: Create balance
issuer->antaca: Create balance for this enduser
antaca->antaca: Create balance
issuer<--antaca: Balance created
ims<-antaca: New balance generated event
ims->ims: Create IBAN number for new balance
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.

Transfer funds

After creating a balance and generating an IBAN number, you can perform fund transfer operations. Funds can be transferred in two directions: sending funds to a recipient's IBAN and receiving funds into the balance using the assigned IBAN.

Depending on the origin of the IBAN and the countries of the sender's and recipient's accounts, the transfer may be processed as an internal, Elixir, SEPA, or SWIFT transfer. Transfer times may vary depending on the method used. Additional fees may also apply.

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

Transfer type	Condition	Potential transfer time
Internal	The sender's IBAN and the recipient's IBAN indicate the Antaca balance within the same instance.	Instant
Elixir	The IBAN currency of the recipient and sender must be PL. The funds must be in Polish zloty.	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.	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.	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.	Max 1 day Can not be instant

Integrated Banks

Our cooperation with the payment institution has enabled us to integrate with the banks listed below. This allows us to process transfers ordered by your end users who have accounts generated in Antaca. The list of integrated banks is growing regularly, and we actively invite banking partners to join this cooperation. Please contact us if you are interested in partnering with us in offering IBAN services.

Integrated bank	Elixir	SEPA	SWIFT
ZEN	Not available	Available	Not available
Pekao	Available	Available	Available

Supported currencies

Integrated bank	PLN	EUR	USD
ZEN	Not available	Available	Not available
Pekao	Available	Available	Available