Applies to API Package: Virtual IBANs (v4.0) by Banca Sella
This article provides a quick reference on how to integrate your backend with Fabrick Platform Virtual IBANs solution provided by Banca Sella.
The following sections assume that you have successfully onboarded on Fabrick Platform and have subscribed at least the following API packages:
Introduction
The Virtual IBANs solution is a powerful set of APIs that allow you to extend the capabilities of your cash account in order to provide advanced features for reconciliation of incoming payments.
A Virtual IBAN is essentially an alias for your actual account IBAN. This concept is very simple, yet powerful, since it enables easyness of segregation for the incoming/outgoing transactions on your account.
Segregation of transaction flows on your account is a basic concept to allow better reconciliation, inspired by the well-known principle of divide-et-impera: the best way to solve a complex problem is to divide it in many simpler sub-problems, and face these smaller and easier sub-problems one at a time, individually.
The following sections will provide a description of some use-case scenarios where Virtual IBANs help to address reconciliation problems, and a quick tutorial on how to actually integrate the service in your backend.
Use-Case Scenarios
The power of creating aliases for your actual cash account IBAN allows you to implement a variety of solutions based on your operational needs. This section provides a description of some common use cases where Virtual IBANs prove to be effective.
Utilities and large corporates. As one of the most critical parts of your business is to correctly keep track of your customers' payments, Virtual IBANs may greatly help in doing this. You may assign a Virtual IBAN to each one of your customers to automatically identify the payments received from any of them. If the payment flow received from your customer is so large to be still hardly manageable, you may even assign a single Virtual IBAN to each one of the expected payments.
Once set up, this configuration will allow your systems to automatically match the subject from which the payment was sent.
Payment Institutions and e-Wallet providers. In these case, the efficiency of your processes rely on the ability of keeping track of who receives what, and updating your internal accounting accordingly. Assigning a Virtual IBAN to each one of your customers, wallets, card, or whatever service will help you to easily route incoming payments to the correct customer, and will allow your customers to have a custom IBAN address assigned exclusively.
Plus, you can even issue payments through each Virtual IBAN, providing an even more customized service to your customers.
Please note that the entitlement of each Virtual IBANs is always the same of the entitlement of your cash account. Due to regulatory compliance, it is not possilble to change the entitlement of any Virtual IBAN.
Managing Virtual IBANs
As we previously discussed, a Virtual IBAN is nothing more than a simple alias of the actual IBAN address of your cash account. The management of each Virtual IBAN always relies upon its parent account.
Creating a Virtual IBAN
You can create a Virtual IBAN by calling the POST Create Virtual IBAN endpoint. The input body only contains the optional textual description of the new Virtual IBAN.
In the output payload you will find the new Virtual IBAN, together with some contextual details such as the date of creation.
Once created, a Virtual IBAN is immediately active and can be used to receive and issue payments based on your use-case scenario.
You can retrieve the full list of Virtual IBANs (either ACTIVE or INACTIVE) with the GET Virtual IBANs endpoint.
Matching Transactions
Once a Virtual IBAN is in use, you may want to match transactions passing through it. There are two different ways to achieve this goal.
Retrieving transactions with GET Virtual IBAN Transactions endpoint. In this case, the answer will provide the transaction list of the sole transactions that have passed through the specified Virtual IBAN. This approach is useful whenever you may want to keep track of what is happening on a specific Virtual IBAN (e.g., if you need to display the transaction list of one of your customers' wallets).
Retrieving all the transactions from the parent account with GET Virtual IBAN Parent Account Transactions endpoint. In this case, the answer is the full list of all transactions of your actual cash account, each one optionally enriched with a isVirtual flag indicating whether the transaction is related to a Virtual IBAN or not. If yes, the specific Virtual IBAN is also provided. This approach is useful whenever you need to match who has sent payments to match expected transactions.
Issuing Payments
You can issue payments through a Virtual IBAN by calling the POST Create Virtual IBAN Money Transfer endpoint. The outgoing payment will debit the balance of the Virtual IBAN parent account, and will display the Virtual IBAN as the debtor account address.
Currently, we support only money transfer payments (either SEPA Credit Transfers or SWIFT transfers).
Once created, a money transfer can be managed as usual with the endpoints of the API package Payments / Money Transfers (v4.0) by Banca Sella.
Disabling a Virtual IBAN
You can disable a Virtual IBAN by calling the PUT Virtual IBAN Inactive endpoint.
Please note that once disabled, a Virtual IBAN cannot be activated anymore. So, be careful to deactivate since if the Virtual IBAN was used by any of your customers, they will receive errors when heading payments towards it.