Overview

This document provides a high-level description of the functionalities offered by the IBAN Management Service. The service enables management of the master account assigned to your institution as the Partner, as well as virtual accounts of endusers- including corporations. Within the service, it is possible to generate accounts, receive transfers, and send them. 

The implementation of the service requires the payment institution to open a master account with a partnering bank. To initiate this process, please contact our Sales Department.

Abbreviations

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

Terminology

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

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 Partner. Processes such as transaction validation, debiting and topping up balances, and saving transaction history per enduser are handled on our side.

IBAN Management API

A backend component that, by communicating with internal and external services, enables the management of master and virtual accounts, including their creation and the execution of transfers. 

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 and managing balances. Each account must be assigned to a balance in order to receive and initiate transfers. It is possible to automatically generate a virtual account based on a balance creation event in Antaca, or manually- using the appropriate API method or through the Admin Panel, which also requires the balance to be created beforehand. The IBAN Management Service also communicates with Antaca to debit or top up the balance of a user, corporation, or Partner.

Deployment in Antaca is required for bank account generation and transfer execution.

Transaction History Core

A backend component responsible for storing the history of performed transactions. The history is available in the Admin Panel as well as directly through the API. Configuration in THC is also available, allowing you to receive notifications.

Admin Panel

A tool for Partners to work with Verestro services. The main purpose of Admin Panel is to provide a web-based environment with the ability to manage Partner service actions. The features available in the Admin Panel within the IBAN service are accessible in a dedicated section. Depending on operator permissions, it is possible to generate accounts, view generated accounts, monitor transactions, and manage AML-related decisions.

Business Control

A platform that enables companies to manage their expenses. The platform’s functionalities can be found in a dedicated section. As part of the IBAN Management Service, it is possible to initiate transfers directly from the UI- both by you and corporations.

Application details

The IBAN Management Service enables the execution- receiving and sending-of various types of transfers. The available types depend on the sender’s and recipient’s countries, the transfer currency, as well as the capabilities of the respective bank. 

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.

IBAN generating

The basis of the IBAN Management Service is a master account opened in a bank by a payment institution. Once a master account is opened, you will receive an IBAN prefix, which allows you to generate account numbers for your endusers and associate these users with your integration. The IBAN prefix is assigned to your account in the Verestro system during configuration. 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 account in our system.

A virtual account can be created in the following ways:

• Automatically after balance creation – once the KYC process is approved and the balance is created, the account will be generated automatically for the user. 

  In the case of a corporation, a successfully completed KYB process is required, as well as providing the corporation entity with an address using the Lifecycle API.

@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 "Partner 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

• Via API – use the dedicated method POST /secure/bank-accounts. To use this method, the balance must be created before attempting to create the account.

• In the Admin Panel – by navigating to the section with endusers and their balances, it is possible to generate an account for a specific balance. This action requires appropriate permissions.

Note: Only one bank account number can be assigned to one balance. The account will be created in the currency of the balance.

IBAN structure

Each IBAN has a specific structure. The IBAN structure is defined in ISO 13616-1 and consists of:

• two-letter ISO 3166-1 country code;
• two check digits;
• up to thirty alphanumeric characters for a BBAN (Basic Bank Account Number) which has a fixed length per country and, included within it, a bank identifier with a fixed position and a fixed length per country. 

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

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 bank account 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.

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 you and your endusers 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.

Supported transfer types

Supported currencies

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

The REST API implementation model was created for Partners 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 endusers 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. Partner authorization is performed by checking the signature in the x509 certificate, which was generated in the context of your Partner 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 "Partner App" as issuer
participant "Verestro" as ims
note right of user: In this case user authentication is Partners 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 Partner 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 Partners who want to share the IBAN Management Service solution through their mobile application. After connecting the appropriate libraries provided by the SDK, your endusers 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 enduser authorization. The mobile SDK is then responsible for communication with the proper Verestro server methods.

Important! Implementation is work in progress...