# IBAN Management

Verestro IBAN Management Service was created for Customers who want to provide their endusers the possibility to pay by IBAN. This solution allows Customer's endusers to top up their balances via a bank transfer and to make transfers from bank to bank account.

# Introduction

Verestro IBAN Management Service was created for Customers who want to provide their endusers the possibility to pay by IBAN. This solution allows Customer's endusers to top up their balances via a bank transfer and to make transfers from bank to bank account. As part of the integration, it is also possible to create an Admin Panel for the Customer. Admin Panel allows Customer to track the history of transfers made using the IBAN Management solution.

<p class="callout info">The solution is available to Customers integrated with Antaca. For more information about Antaca service please open [this link](https://developer-quicko.verestro.com/books/card-management-system)</p>

## How to connect with us?

Verestro provides access to the solution in in two ways, depending on the Customer requirements. The Customer can access the IBAN Management solution through Mobile SDK or REST API implementation models.

### Mobile SDK

Verestro provides an integration model that allows Customers to get and show generated IBANs on the mobile applications. Methods in this integration model are secured with an authorization token from Mobile DC. More detailed information about the integration with IBAN Management for mobile are available in <span lang="en-US">Technical documentation chapter</span>**.** Verestro actively supports the Customer in the integration process.

### REST API

Verestro provides an integration model that allows Customers to get and show generated IBAN's through server to server connection. Methods in this integration model requires x509 certificate authentication. More detailed information about IBAN Management API integration are available in <span lang="en-US">Technical documentation chapter</span>**.** Verestro actively supports the Customer in the integration process

# Overview

<span lang="en-US">This document provides high level description of functionalities offered by IBAN Management Service. Solution allows to generate IBAN as a reaction to 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 the Verestro backend. Detailed information about the integration is available in the Technical documentation chapter. </span>

<span lang="en-US">To use the application the creation of the Customer account in the IBAN Management Service and integration with the Antaca service - which is responsible for generating balances - are required. More information about balance generating is available in the Antaca Create User Balance documentation. The IBAN is created in response to the created balance and is a kind of indicator for this balance.</span>

## <span lang="en-US">Abbreviations</span>

<span lang="en-US">This section shortly describes abbreviations and acronyms used in the document.</span>

<table border="1" cellpadding="1" cellspacing="0" id="bkmrk-abbreviation-descrip" width="712"><tbody><tr valign="TOP"><td bgcolor="#002060" width="353">**Abbreviation**

</td><td bgcolor="#002060" width="353">**Description**

</td></tr><tr valign="TOP"><td width="353">SDK

</td><td width="353">Software Development Kit

</td></tr><tr valign="TOP"><td width="353">API

</td><td width="353">Application Programming Interface

</td></tr><tr valign="TOP"><td width="353">IBAN

</td><td width="353">International Bank Account Number

</td></tr><tr valign="TOP"><td width="353">OS

</td><td width="353">Operative System

</td></tr><tr><td>IMS

</td><td>IBAN Management Service

</td></tr><tr><td>THC

</td><td>Transaction History Core

</td></tr><tr valign="TOP"><td width="353">AP

</td><td width="353">Admin Panel

</td></tr></tbody></table>

## Terminology

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

<table border="1" cellpadding="1" cellspacing="0" id="bkmrk-abberations-descript" width="708"><tbody><tr valign="TOP"><td bgcolor="#002060" width="129">**Name**

</td><td bgcolor="#002060" width="573">**Description**

</td></tr><tr valign="TOP"><td width="129">IBAN

</td><td width="573">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.

</td></tr><tr><td>Base IBAN / IBAN prefix

</td><td>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.

</td></tr><tr valign="TOP"><td width="129">Balance

</td><td width="573">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.

</td></tr><tr><td>Customer

</td><td>Institution which is using Verestro products. Basically Customer can be called Verestro client.

</td></tr><tr><td>IBAN Issuing Institution

</td><td>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.

</td></tr><tr><td>Bank

</td><td>The Bank contacts the IBAN Issuing Institution informing about transfers that need to be settled.

</td></tr><tr><td>Currency

</td><td>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.

</td></tr><tr><td>Transaction file

</td><td>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.

</td></tr></tbody></table>

## IBAN Management Service key components

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

<table border="1" cellpadding="1" cellspacing="0" id="bkmrk-component-descriptio" width="712"><tbody><tr valign="TOP"><td bgcolor="#002060" width="214">**Component**

</td><td bgcolor="#002060" width="492">**Description**

</td></tr><tr valign="TOP"><td width="214">IBAN Management Service

</td><td width="492">Backend component that allows Customer to issue 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. In addition, IMS is responsible for validating each transfer order.

</td></tr><tr valign="TOP"><td width="214">Antaca

</td><td width="492">Backend component that is responsible for creating balances for Customers. After creating the balance, Antaca sends an event. On the basis of this event the IMS 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).

</td></tr><tr valign="TOP"><td width="214">Admin Panel

</td><td width="492">Web component that allows to create a panel for the Customer so that he can see his endusers' IBAN numbers (the IBAN number is not a sensitive value) and can track transactions performed by these IBAN's. Through the Admin Panel, transaction files are also uploaded. To see an sample view of the Panel and the user experience of the Admin Panel, please visit the Use Cases chapter.

</td></tr><tr valign="TOP"><td width="214">Transaction History Core

</td><td width="492">Backend component responsible for storing details of the performed transactions. Transaction information stored in THC is provided, among others, to the Admin Panel so that allows the Customer to tracking transaction made by his endusers. Transactions stored in THC are also transferred to the enduser's as a history of debits and account top-ups. Eventually THC is also able to send transaction notifications to the Customer.

</td></tr></tbody></table>

The diagram below shows each component involved in the IBAN Management Service processes and the dependencies between them:

[![image-1676368942013.drawio (1).png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1676368942013-drawio-1.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1676368942013-drawio-1.png)

### Implementation models

<span lang="en-US">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.</span>

<table border="1" id="bkmrk-mobile-sdk-integrati" style="width: 100%;"><tbody><tr><td style="width: 12.967388%;">Mobile SDK</td><td style="width: 87.032612%;">Integration via mobile SDK has been made available to Customers who want to connect to the IBAN Management service via mobile applications. In this solution, the Customer authorizes himself using a session token previously obtained from the Mobile DC service. Details of integration via mobile SDK are available in the Technical documentation chapter.</td></tr><tr><td style="width: 12.967388%;">REST API</td><td style="width: 87.032612%;">Server-to-server integration has been made available for 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.</td></tr></tbody></table>

## IBAN Management Service details

The chapter describes what possibilities the IBAN Management Service offers and what are the most important processes of the solution.

<table border="1" id="bkmrk-iban-generating-an-e"><tbody><tr><td>[IBAN generating](https://developer.verestro.com/books/iban-management/page/overview#bkmrk-iban-structure)</td><td>An element of the solution that is responsible for generating IBANs using a special algorithm based on the base IBAN that Customer received from the IBAN Issuing Institution.</td></tr><tr><td>[IBAN transfer receiving](https://developer.verestro.com/books/iban-management/page/overview#bkmrk-iban-transfer-receiv)</td><td>An element of the solution responsible for handling incoming transfers to the received IBAN and thus for initiating the process of topping up recipient's balance.</td></tr><tr><td>[IBAN transfer sending](https://developer.verestro.com/books/iban-management/page/overview#bkmrk-iban-transfer-sendin)</td><td>An element of the solution responsible for handling outgoing transfers and thus for initiating the sender's balance charging process.</td></tr></tbody></table>

### IBAN generating

The IBAN generation process can be divided into two stages. Each of these stages is described in this chapter. The first and most important step is to delivery of the base IBAN to Verestro by the Customer. The base IBAN is generated by the IBAN Issuing Institution, which is a Verestro partner. After receiving the base IBAN, Verestro will assign it to the Customer's account.   
Based on the base IBAN, each subsequent IBAN in the context of the Customer will be created. This step is performed only once during the Onboarding process.

The second step is to create an Antaca balance which means that at this stage the Customer should already be integrated with the Antaca service. IBAN is an indicator of the balance, so without the created balance, the use of IBANs is not possible. The Customer integrated with Antaca service is able to provide its endusers with the ability to generate balances and thus creating IBANs assigned to these balances. Balance creation method is described in Antaca Create User Balance documentation.

The diagram below shows the creation of the new IBAN step by step.

@startuml  
skinparam ParticipantPadding 30  
skinparam BoxPadding 30  
skinparam noteFontColor #FFFFFF  
skinparam noteBackgroundColor #002060  
skinparam noteBorderColor #002060  
skinparam noteBorderThickness 1  
skinparam sequence {  
ArrowColor #002060  
ArrowFontColor #002060  
ActorBorderColor #002060  
ActorBackgroundColor #FFFFFF  
ActorFontStyle bold  
ParticipantBorderColor #002060  
ParticipantBackgroundColor #002060  
ParticipantFontColor #FFFFFF  
ParticipantFontStyle bold  
LifeLineBackgroundColor #002060  
LifeLineBorderColor #002060  
}  
participant "Endser" as user  
participant "Customer App" as issuer  
participant "IBAN Management Service" as ims  
participant "Antaca" as antaca  
note right of user: Enduser creates new balance  
user-&gt;issuer: Create balance  
issuer-&gt;antaca: Create balance for this enduser  
ims&lt;-antaca: New balance generated event  
ims-&gt;ims: Create IBAN number for new balance  
issuer&lt;-antaca: Balance created  
issuer-&gt;ims: Get enduser IBAN  
issuer&lt;-ims: Return IBAN number  
user&lt;-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:

<table border="1" id="bkmrk-two-letter-country-c"><tbody><tr><td>Two-letter country code according to the ISO-3166 standard (for Poland these are the letters PL).

</td></tr><tr><td>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.

</td></tr><tr><td>The account number may contain numbers 0-9 and capital letters of the Latin alphabet A-Z.

</td></tr></tbody></table>

<p class="callout info">**Example:** Polish IBAN numbers consist of 2 letters of the country and 26 digits according to the following division PL00123456789090909090909090.  
</p>

<table border="1" id="bkmrk-pl%C2%A0-2-letters-of-the"><tbody><tr><td>PL </td><td>2 letters of the country.</td></tr><tr><td>00 12345678</td><td>2 digits of the checksum and 8 digits tracking a given bank and, for example, it's specific branch.</td></tr><tr><td>9090909090909090</td><td>16 digits tracking a specific account.</td></tr></tbody></table>

#### Supported currencies

<table border="1" id="bkmrk-pln-polish-zloty-eur"><tbody><tr><td>PLN</td><td class="align-right">Polish zloty</td></tr><tr><td>EUR</td><td class="align-right">Euro</td></tr><tr><td>USD</td><td class="align-right">American dollar</td></tr><tr><td>GBP</td><td class="align-right">British pound sterling</td></tr><tr><td>CHF</td><td class="align-right">Swiss franc</td></tr><tr><td>AUD</td><td class="align-right">Australian dollar</td></tr><tr><td>CAD</td><td class="align-right">Canadian dollar</td></tr><tr><td>CZK</td><td class="align-right">Czech koruna</td></tr><tr><td>DKK</td><td class="align-right">Danish krone</td></tr><tr><td>NOK</td><td class="align-right">Norwegian krone</td></tr><tr><td>SEK</td><td class="align-right">Swedish krone</td></tr><tr><td>HUF</td><td class="align-right">Hungarian forint</td></tr><tr><td>JPY</td><td class="align-right">Japanese yen</td></tr><tr><td>MXN</td><td class="align-right">Mexican peso</td></tr><tr><td>ZAR</td><td class="align-right">South african rand</td></tr><tr><td>TRY</td><td class="align-right">Turkish lira</td></tr><tr><td>BGN</td><td class="align-right">Bulgarian lev</td></tr><tr><td>RON</td><td class="align-right">omanian leu</td></tr><tr><td>CNY</td><td class="align-right">Chinese yuan</td></tr><tr><td>THB</td><td class="align-right">Thai baht</td></tr><tr><td>ILS</td><td class="align-right">Israeli new shekel</td></tr><tr><td>HKD</td><td class="align-right">Hong Kong dollar</td></tr></tbody></table>

### Transfer receiving

This functionality allows enduser to receive transfers. Endser which is using Customer's application is able to share his IBAN to potential payer. This type of transfer is a transaction that top ups enduser's balance. As receiving an incoming transfer requires only to provide IBAN to his potential payer, the only method with which the Customer must integrate is `<a href="https://developer.verestro.com/books/iban-management/page/technical-documentation">getIban</a>` or `<a href="https://developer.verestro.com/books/iban-management/page/technical-documentation">getIbanMobile</a>` - depending on the implementation model. For integration details please visit Technical documentation chapter.

### Transfer sending

This functionality allows enduser to order outgoing transfers. Enduser which is using Customer's application is able to sends money on a given IBAN. The outgoing transfer is a transaction that charges enduser's balance.

<p class="callout warning">Implementation work in progress...</p>

## Admin Panel

Using the Admin Panel service allows the Admin Panel operator to perform various actions related to IBAN transfers. Actions of this type include, among others, filtering endusers and their IBANs, tracking the history of enduser's transactions and their account balances, as well as execution of the ordered transfers. The operator of the Admin Panel is an employee of a given institution. Basicly it can be a person representing the Customer's institution or an employee of the IBAN Issuing Institution. Each of the operators has an assigned role in the Admin Panel, which determines what actions in the Admin Panel they can perform. For more detailed information please visit Admin Panel use cases chapter.

<p class="callout danger">After creating an Admin Panel instance in the context of IBAN Management Service for a given Customer, remember to provide the domain of this instance. We need to add this domain to the whitelist. Otherwise, IBAN Management Service API will reject every request with HTTP status 403 - Forbidden.  
  
*Example domain to be provided for whitelisting: https://admin-panel-customername.verestro.com*</p>

# Use cases

This chapter contains the description of the processes taking place in the IBAN Management Service from the point of view of the Customer and the end user. Information on how to integrate with the solution has also been added.

## IBAN transfer receiving

This functionality allows user to receive transfers. User which is using Customer's application is able to share his IBAN to potential payer. This type of transfer is a transaction that top ups user's balance. As receiving an incoming transfer requires only to provide IBAN to his potential payer, the only functionality which the Customer must handle is IBAN displaying. For integration details please visit Technical documentation chapter.

### Display IBAN

The user who logs in the Customer application sees his balance and the IBAN that is assigned to this balance. This allows him to share such IBAN to a potential payer so that the payer can make a transfer to the user's account. Having a visible IBAN, the user can also top up his balance by making a bank transfer from his external account. The IBAN can be displayed by using the `<a href="https://developer.verestro.com/books/iban-management/page/technical-documentation">getIban</a>` and `<a href="https://developer.verestro.com/books/iban-management/page/technical-documentation">getIbanMobile</a>` methods depending on the implementation model used by the Customer. The implementation model also defines the method of Customer authorization in the IMS service. In the case of the Mobile SDK implementation model, the Customer authenticates using a session token received from Mobile DC. In the case of the REST API implementation model, the Customer authenticates through signed x509 certificate.

#### Mobile SDK integration

The Mobile SDK implementation model was created for Customers who want to share the IBAN Management Service solution through their mobile application. In order for the Customer to be able to provide its users with access to their IBAN's, it is necessary to make a request to the IMS service. The functionality that returns the user's IBANs is secured - Customer authorization is required. This process consists in transferring a Mobile DC session token during the request to get the list of IBANs. To integrate with the getIbanMobile method, please visit the Technical documentation chapter.

@startuml  
skinparam ParticipantPadding 30  
skinparam BoxPadding 30  
skinparam noteFontColor #FFFFFF  
skinparam noteBackgroundColor #002060  
skinparam noteBorderColor #002060  
skinparam noteBorderThickness 1  
skinparam sequence {  
ArrowColor #002060  
ArrowFontColor #002060  
ActorBorderColor #002060  
ActorBackgroundColor #FFFFFF  
ActorFontStyle bold  
ParticipantBorderColor #002060  
ParticipantBackgroundColor #002060  
ParticipantFontColor #FFFFFF  
ParticipantFontStyle bold  
LifeLineBackgroundColor #002060  
LifeLineBorderColor #002060  
}  
participant "User" as user  
participant "Customer App" as issuer  
participant "Mobile DC" as mdc  
participant "IBAN Management Service" as ims  
note right of user: User opens Customer mobile app  
user-&gt;issuer: Check my IBAN  
issuer-&gt;mdc: Get session token  
issuer&lt;-mdc: Return session token  
issuer-&gt;ims: Get IBAN by balance ID  
issuer--&gt;ims: Provide Mobile DC session token  
ims-&gt;ims: Validate session token  
issuer&lt;-ims: Return user's IBAN  
user&lt;-issuer: Display IBAN to the user  
@enduml

#### REST API integration

The REST API implementation model was created for Customers who want to connect with the IBAN Management Service through their backend. In order for the Customer to be able to provide its users with access to their IBANs, it is necessary to make a request to the IMS service. The access to the IMS is secured and requires the Customer to authenticate with [x509 certificate](https://developer.verestro.com/books/iban-management/page/technical-documentation#bkmrk-how-to-generate-csr-). After successful authentication it is possible to get the list of IBANs. To integrate with the getIban method, please visit the [Technical documentation chapter](https://developer.verestro.com/books/iban-management/page/technical-documentation).

@startuml  
skinparam ParticipantPadding 30  
skinparam BoxPadding 30  
skinparam noteFontColor #FFFFFF  
skinparam noteBackgroundColor #002060  
skinparam noteBorderColor #002060  
skinparam noteBorderThickness 1  
skinparam sequence {  
ArrowColor #002060  
ArrowFontColor #002060  
ActorBorderColor #002060  
ActorBackgroundColor #FFFFFF  
ActorFontStyle bold  
ParticipantBorderColor #002060  
ParticipantBackgroundColor #002060  
ParticipantFontColor #FFFFFF  
ParticipantFontStyle bold  
LifeLineBackgroundColor #002060  
LifeLineBorderColor #002060  
}  
participant "User" as user  
participant "Customer App" as issuer  
participant "IBAN Management Service" as ims  
note right of user: User opens Customer web app  
user-&gt;issuer: Check my IBAN  
issuer-&gt;ims: Get IBAN by balance ID  
issuer--&gt;ims: Provide x509 certificate  
ims-&gt;ims: Validate certificate signature  
issuer&lt;-ims: Return user's IBAN  
user&lt;-issuer: Display IBAN to the user  
@enduml

## IBAN transfer sending

This functionality allows user to order outgoing transfers. User which is using Customer's application is able to sends money on a given IBAN. The outgoing transfer is a transaction that charges user's balance.

<p class="callout warning">Implementation work in progress...</p>

## Admin Panel

One of the additional functionalities that Verestro provides is the creation of an administration panel that allows the Customer to track the history of users' transactions - individual banking operations such as debiting or topping up the account with the transfer IBAN are visible. The Admin Panel also provides information such what IBAN is assigned to the secified user and and which balance this IBAN refers to. The Admin Panel is configured mainly on the Verestro side. Each instance of the Admin Panel is issued per Customer.

The below diagram shows the processes of filtering users and their IBAN numbers:

<p class="callout info">Process available for Admin Panel operetor with every type of Admin Panel operator roles.</p>

@startuml  
skinparam ParticipantPadding 30  
skinparam BoxPadding 30  
skinparam noteFontColor #FFFFFF  
skinparam noteBackgroundColor #002060  
skinparam noteBorderColor #002060  
skinparam noteBorderThickness 1  
skinparam sequence {  
ArrowColor #002060  
ArrowFontColor #002060  
ActorBorderColor #002060  
ActorBackgroundColor #FFFFFF  
ActorFontStyle bold  
ParticipantBorderColor #002060  
ParticipantBackgroundColor #002060  
ParticipantFontColor #FFFFFF  
ParticipantFontStyle bold  
LifeLineBackgroundColor #002060  
LifeLineBorderColor #002060  
}  
participant "AP Operator" as issuer  
participant "Admin Panel" as ap  
participant "IBAN Management Service" as ims  
participant "Transaction History Core" as thc  
note right of issuer: Customer logs in Admin Panel  
issuer-&gt;ap: Log in  
issuer&lt;-ap: Success  
note right of issuer: Customer filter IBANs list  
issuer-&gt;ap: Get IBANs  
ap-&gt;ims: Get IBANs by specified query  
ap&lt;-ims: Return list of found IBANs  
issuer&lt;-ap: Show list of found IBANs  
note right of issuer: Customer filter transaction history list  
issuer-&gt;ap: Get transaction history  
ap-&gt;thc: Get transaction history by specified query  
ap&lt;-thc: Return list of found transactions  
issuer&lt;-ap: Show list of found transactions  
@enduml

The below diagram shows the processes of the uploading transaction file and the execution of the IBAN transfers:

<p class="callout info">Process available for Admin Panel operetor with Admin Panel `ADMIN` role.</p>

@startuml  
skinparam ParticipantPadding 30  
skinparam BoxPadding 30  
skinparam noteFontColor #FFFFFF  
skinparam noteBackgroundColor #002060  
skinparam noteBorderColor #002060  
skinparam noteBorderThickness 1  
skinparam sequence {  
ArrowColor #002060  
ArrowFontColor #002060  
ActorBorderColor #002060  
ActorBackgroundColor #FFFFFF  
ActorFontStyle bold  
ParticipantBorderColor #002060  
ParticipantBackgroundColor #002060  
ParticipantFontColor #FFFFFF  
ParticipantFontStyle bold  
LifeLineBackgroundColor #002060  
LifeLineBorderColor #002060  
}  
participant "AP Operator" as issuer  
participant "Admin Panel" as ap  
participant "IBAN Management Service" as ims  
participant "Antaca" as ant  
participant "Transaction History Core" as thc  
note right of issuer: AP Operator uploads transaction file  
issuer-&gt;ap: Upload transaction file  
ap-&gt;ims: Send transaction file  
note left of ims: The authorization token representing a given Customer in PA is validated   
ims-&gt;ims: Validate Admin Panel authorization token  
ims-&gt;ims: Validate transaction file  
ap&lt;-ims: Validation success  
issuer&lt;-ap: Show validation status  
issuer-&gt;ap: Execute transaction file  
ap-&gt;ims: Order transaction file execution  
ims-&gt;ant: Credit/debit balances based on IBANs from the transaction file  
note left of ant: The x509 certificate of a given Customer context is validated  
ant-&gt;ant: Validate CN  
ims&lt;-ant: Credit/debit result  
ant-&gt;thc: Report transaction  
ims-&gt;ims: Generated transaction report  
ims-&gt;thc: Report transaction  
@enduml

### Views

This chapter contains views and actions to be performed available to the Admin Panel operator regarding the IBAN Management solution. Depending on the role of the operator's account, various actions are available in the Admin Panel. The roles available in the Admin Panel are `EMPLOYEE`, `MANAGER` and `ADMIN`. More information about roles and their permissions are included further in Views chapter subsections.

<p class="callout info">Depending on the Customer's requirements, the permissions in the Admin Panel can be configurable. For example, it is possible that only `ADMIN` and `MANAGER` can add a new balance from the Admin Panel. `EMPLOYEE`, on the other hand, would only be able to perform `read` actions. Detailed information about roles and permissions configurations are available in the Admin Panel Service documentation.</p>

#### Enduser details

Each role is entitled to `read` actions. This means that `EMPLOYEE`, `MANAGER` and `ADMIN` can filter their endusers and check their account details such as assigned balances and IBANs. The option of viewing end users is available in the `CUSTOMERS` / `End Users` tab and has been presented on the picture below:

[![image-1677147920306.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1677147920306.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1677147920306.png)

Using to the available filters in `Endusers` tab, the Admin Panel operator regardless of his Admin Panel role can find a proper user by various filtering criteria - including the IBAN number. The entered filtering criteria can be cleared using the `Clear all` button in the upper right corner. Available filtering options have been presented on the picture below:

[![image-1676554736454.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1676554736454.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1676554736454.png)

Such the Admin Panel operator is also able to view the details of a given end user by selecting end user's record from the list of all end users. In the end user details section, there are several tabs dedicated to various functionalities - including `Balances` tab with balances details and the same IBANs assigned to these balances. By selecting the `Reveal` option, the Admin Panel operator can view the end user's IBAN number. From the same view, it is also possible to add a new balance to the end user, which will also generate a new IBAN number. Generating a new balance is possible with the `+Add new balance` button in the lower left corner. The action of generating a new balance is also available for each role of the Admin Panel operator. The described posibilities available in `Balances` tab have been presented on the picture below:

[![image-1676555543719.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1676555543719.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1676555543719.png)

#### Payment history

Each of the Admin Panel operators also has the ability to view the transaction history of all endusers. The option of viewing end users is available in the `CUSTOMERS` / `Payment History` tab and has been presented one the picture below:

[![image-1677150640402.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1677150640402.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1677150640402.png)

Using to the available filters in `Payment history` tab, the Admin Panel operator regardless of his Admin Panel role can find a proper end user's transaction by various filtering criteria. The entered filtering criteria can be cleared using the `Clear all`button in the upper right corner. After specifying the filtering criteria, the operator can also generate a transaction report using the `Generate transaction report` button in the upper right corner.

[![image-1677151269746.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1677151269746.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1677151269746.png)

Such the Admin Panel operator is also able to view the payment history of a given end user by selecting end user's record from the list of all end users. In the end user details section, there are several tabs dedicated to various functionalities - including `Payment history` tab with transaction details performed by selected enduser. The `Payment history` tab have been presented on the picture below:

[![image-1677149382343.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1677149382343.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1677149382343.png)

#### Upload transaction file

<p class="callout info">The following section describes actions allowed only for Admin Panel operators with `ADMIN` role.</p>

This chapter is devoted to views and processes related to uploading transaction files and their execution. These processes can only be performed by operators with ADMIN role rights and persons legally authorized to perform such operations as ordering and executing transactions. The functionality responsible for uploading transaction files is available in the `IBAN MANAGEMENT` / `Upload transaction file` tab and has been presented on the picture below:

[![image-1677152467676.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1677152467676.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1677152467676.png)

  
After selecting the `Upload transaction file` tab, a dropbox intended for uploading transaction file appears. The Admin Panel operator with the `ADMIN` role has permission to upload such file and confirms the upload with the `Submit` button visible in the lower right corner. The dropbox view has been presented on the picture below:

[![image-1677157756676.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1677157756676.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1677157756676.png)

After confirming the upload of the transaction file by the `Submit` button, the validation process begins. During the validation every transaction record contained in the file is checked. The validation result is displayed in the list of uploaded files under the transaction file dropbox.

<p class="callout warning">Each file should have a unique name otherwise there is a risk of overwriting a previously uploaded file with the same name.</p>

After the validation process, information about whether the file is valid or not valid is displayed. The information about the transaction file validation status is presented in the form of a status in the `Status` column. The list of validation statuses and their meanings are available in the Transaction file validation statuses section. If the file validation was successful, then it is possible to execute transaction file. File execution is performed after clicking the `Execute` button in the `Send file`column. Each transaction file can be sent for execution only once to avoid accidental additionally top up or debit of the given balance. If the validation result of the transaction file is negative, then a proper status in the `Status` column is presented and the validation report file is generated, available for download by the Admin Panel operator. The Admin Panel operator can download such validation report by clicking on the `arrow button` in the `Report link` column. Appearance of the list of uploaded transaction file has been presented on the picture below:

[![image-1677157946455.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1677157946455.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1677157946455.png)

##### Transaction file validation statuses

<table border="1" cellpadding="1" cellspacing="0" id="bkmrk-abbreviation-descrip" width="712"><tbody><tr valign="TOP"><td bgcolor="#002060" width="353">**Status**

</td><td bgcolor="#002060" width="353">**Description**

</td></tr><tr valign="TOP"><td width="353">Validated

</td><td width="353">Transaction file upload completed successfully. Validation returned positive status. Ready for execution.

</td></tr><tr><td>Executed

</td><td>Transaction file already executed.

</td></tr><tr><td>Executing

</td><td>Transaction file execution is progress.

</td></tr><tr><td>Pending

</td><td>Transaction file validation in progress. Execution is not possible.

</td></tr><tr><td>Invalid

</td><td>Transaction file validation returned nagative status. Execution is not possible.

</td></tr></tbody></table>

#### Execute files reports

<p class="callout info">The following section describes actions allowed only for Admin Panel operators with `ADMIN` role.</p>

This chapter is devoted to views and process related to downloading executed transaction reports. These processes can only be performed by operators with ADMIN role rights and persons legally authorized to perform such operations as ordering and executing transactions. The functionality responsible for uploading transaction files is available in the `IBAN MANAGEMENT` / `Upload transaction file` tab and has been presented on the picture below:

[![image-1677161299855.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1677161299855.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1677161299855.png)

After selecting the `Executed files reports` tab, a list of the all transaction reports appears. List contains information about each of the generated reports: date of the report generation, name of the report and it's identifier. There is also posibility to download such report by clicking on the `arrow button` in the `Report link` column. The list of the executed transaction reports view has been presented on the picture below:

[![image-1677235485592.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1677235485592.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1677235485592.png)

``

## Notification after transaction

One of the additional functionalities offered in the IMS solution is sending transaction notifications to the Customer. The notification is sent in the form of an event that should be handled by the Customer. The Customer should create `POST`type endpoint to allow us to send such an event.

```JavaScript
POST https://example-customer-site.com/transaction-event

{
  "id": 20,
  "timestamp": 1665557034
}
```

Transaction event contains the transaction identifier as has been shown in example above. Using this identifier, the Customer can get the details of a given transaction using the appropriate method. It is also possible to get a list of all transactions. Implementation details are available in the technical documentation of the Transaction History Core service.

@startuml  
skinparam ParticipantPadding 30  
skinparam BoxPadding 30  
skinparam noteFontColor #FFFFFF  
skinparam noteBackgroundColor #002060  
skinparam noteBorderColor #002060  
skinparam noteBorderThickness 1  
skinparam sequence {  
ArrowColor #002060  
ArrowFontColor #002060  
ActorBorderColor #002060  
ActorBackgroundColor #FFFFFF  
ActorFontStyle bold  
ParticipantBorderColor #002060  
ParticipantBackgroundColor #002060  
ParticipantFontColor #FFFFFF  
ParticipantFontStyle bold  
LifeLineBackgroundColor #002060  
LifeLineBorderColor #002060  
}  
participant "Transaction History Core" as THC  
participant "Customer's Server" as issuer  
THC-&gt;issuer: Send notification event  
issuer-&gt;THC: Get transaction details by received transaction id  
issuer&lt;-THC: Return transaction details  
@enduml

<p class="callout info">This is an optional feature, but we recommend using it.</p>

# Onboarding

This chapter describes the steps that must be performed in order for the Customer to use the IBAN Management Service solution.

<table border="1" id="bkmrk-"><tbody><tr><td>- [ ] Integration with Antaca Service. This requirement is needed so that the Customer has his own dedicated space to generate and store his users' balances in the Verestro system.

</td></tr><tr><td>- [ ] Signing an agreement with the IBAN Issuing Institution. Verestro actively helps the Customer to go through this step. This institution issues the base IBAN and settles transfers made in the context of the Customer.

</td></tr><tr><td>- [ ] Providing the base IBAN to Verestro. This step is directly related to signing an agreement with the IBAN Issuing Institution, which issues such a base IBAN to Customer. On its basis, IBANs of each user of the integrated Customer are generated.

<p class="callout info">Each base IBAN is created for a specific currency. For example, if the Customer wants IBANs to be generated in EUR and PLN, he must provide two base IBANs - one in EUR and the other one in PLN.</p>

</td></tr><tr><td>- [ ] Creation of a technical balance in Antaca. This is the balance to which failed transfers will be credited. For example, a transfer to IBAN, which does not exist in the Verestro system.

</td></tr><tr><td>- [ ] Generating and delivering an x​​509 certificate for signing. This certificate will be used to authorize the Customer.
- [ ] x509 commonName - this value is provided by the Customer in the CN parameter when [generating the CSR file](https://developer.verestro.com/books/iban-management/page/technical-documentation#bkmrk-how-to-generate-csr-).

<p class="callout info">This step is only required for server to server integration. Mobile-server integrating Customers can ignore this point.</p>

</td></tr><tr><td>- [ ] Integration with Mobile DC secure. The Mobile DC service allows you to generate a session token needed to authorize the Customer and get the context of the appropriate user.

<p class="callout info">This step is only required for mobile to server integration. Server-server integrating Customers can ignore this point.</p>

</td></tr></tbody></table>

<p class="callout danger">If the Customer has an Admin Panel created it is necessary to provide the domain of this instance. We need to add this domain to the whitelist. Otherwise, IBAN Management Service API will reject every request with HTTP status 403 - Forbidden.  
  
*Example domain to be provided for whitelisting: https://admin-panel-customername.verestro.com*</p>

# Technical documentation

#### Server to server integration

This chapter provides technical information about the integration with IBAN Management Service using REST API integration model.

@swagger="[https://iban-management.upaid.pl/doc/server.yaml](https://iban-management.upaid.pl/doc/server.yaml)"

##### How to generate CSR file

To generate CSR file follow below instruction. The file must be sent to Verestro - we will sign it and return a valid certificate in a response.

<table border="1" id="bkmrk-common-name-%28cn%29---v"><tbody><tr><td bgcolor="#002060" width="353">**An example completed certificate fields**

</td></tr><tr><td>`Common Name (CN) - V-Companyname-ApplicationName`</td></tr><tr><td>`Organization (O) - Company name`</td></tr><tr><td>`Organizational Unit (OU) - free text`</td></tr><tr><td>`City/Locality (L) - free text`</td></tr><tr><td>`State/County/Region (S) - free text`</td></tr><tr><td>`Country (C) - Two-letter country code where organization is located.`</td></tr><tr><td>`Email Address - Email in case of forced renewal of the change`</td></tr></tbody></table>

**Example CSR generation command:** `openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=V-SomeCompany-OurApplication /O=SomeCompany /OU=Business /L=Lublin /S=Lubelskie /C=PL /Email Address=example@user.com'`

#### Mobile to server integration

This chapter provides technical information about the integration with IBAN Management Service using Mobile SDK integration model.

@swagger="https://iban-management.upaidtest.pl/swagger-ui/index.html?urls.primaryName=mobile"

<p class="callout warning">There is a temporary issue with rendering mobile [technical documentation](https://iban-management.upaidtest.pl/swagger-ui/index.html). To view the technical documentation, please follow [this link.](https://iban-management.upaidtest.pl/swagger-ui/index.html)</p>