---
title: "API"
description: "This endpoint allows you to create a new Virtual IBAN associated with a main account."
url: "https://docs.fabrick.com/en/payment-institution/banking-as-a-service/virtual-iban/dev/api/"
language: "en"
---

# API

## Flow Endpoints

![virutalIbanFlowpng](https://docs.fabrick.com/en/img/payment-institution/banking-as-a-service/virtual-iban/virtual-iban-flow.png)

## Create Virtual IBAN

This endpoint allows you to create a new Virtual IBAN associated with a main account. It allows you to generate a virtual identifier for collections, reconciliations, and categorizations, with a text description if desired.

Example request:

```text
POST /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans
```

Request parameters:

- `accountId` – required; ID of the account on which to create the Virtual IBAN
- `description` – optional; description of the Virtual IBAN in the JSON body

Body example:

```json
{
  "description": "My new virtual IBAN."
}
```

Example response:

```json
{
  "virtualIban": "IT16L03268223000VR000000042",
  "parentAccountId": "14527670",
  "status": "ACTIVE",
  "activatedDate": "2019-07-04",
  "deactivatedDate": null,
  "description": "My new virtual IBAN."
}
```

Response parameters:

- `virtualIban` – the created Virtual IBAN
- `parentAccountId` – ID of the main account
- `status` – status of the Virtual IBAN
- `activatedDate` – activation date
- `deactivatedDate` – deactivation date
- `description` – assigned description

---

## Get Virtual IBANs List

This endpoint returns the list of Virtual IBANs associated with an account, with the option to include inactive ones.

Example request:

```text
GET /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans?showInactive=true
```

Request parameters:

- `accountId` – required; ID of the account
- `showInactive` – optional; if true, inactive Virtual IBANs are also included

Example response:

```json
{
  "list": [
    {
      "virtualIban": "IT16L03268223000VR000000042",
      "parentAccountId": "14527670",
      "status": "ACTIVE",
      "activationDate": "2019-07-04",
      "deactivationDate": null,
      "description": "My new virtual IBAN."
    }
  ]
}
```

Response parameters:

- `list` – list of Virtual IBANs
- `virtualIban` – virtual IBAN
- `parentAccountId` – ID of the main account
- `status` – status of the Virtual IBAN
- `activationDate` – activation date
- `deactivationDate` – deactivation date
- `description` – description

---

## Get Virtual IBAN

This endpoint retrieves information about a single Virtual IBAN identified by its value.

Example request:

```text
GET /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans/{virtualIban}
```

Request parameters:

- `accountId` – required; ID of the account
- `virtualIban` – required; virtual IBAN to look up

Example response:

```json
{
  "virtualIban": "IT16L03268223000VR000000042",
  "parentAccountId": "14527670",
  "status": "ACTIVE",
  "activationDate": "2019-07-04",
  "deactivationDate": null,
  "description": "My new virtual IBAN."
}
```

Response parameters:

- `virtualIban` – virtual IBAN
- `parentAccountId` – ID of the main account
- `status` – status of the Virtual IBAN
- `activationDate` – activation date
- `deactivationDate` – deactivation date
- `description` – description

---

## Deactivate Virtual IBAN

This endpoint allows you to deactivate an existing Virtual IBAN.

Example request:

```text
PUT /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans/{virtualIban}/inactive
```

Request parameters:

- `accountId` – required; ID of the account
- `virtualIban` – required; virtual IBAN to deactivate

Example response:

```json
{
  "result": "OK"
}
```

Response parameters:

- `result` – outcome of the operation

---

## Create Virtual IBAN Money Transfer

This endpoint supports money transfers using a Virtual IBAN as the source.

Example request:

```text
POST /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans/{virtualIban}/money-transfers
```

Body example:

```json
{
  "amount": 100,
  "currency": "EUR",
  "receiverIban": "IT00A0000000000000000000000",
  "description": "Transfer from virtual IBAN"
}
```

Request parameters:

- `accountId` – required; ID of the account
- `virtualIban` – required; source virtual IBAN
- `amount` – transfer amount
- `currency` – currency
- `receiverIban` – recipient IBAN
- `description` – transfer description

Example response:

```json
{
  "transferId": "123456789"
}
```

Response parameters:

- `transferId` – transaction ID

---

## Get Parent Account

Returns the information of the main account associated with a Virtual IBAN.

Example request:

```text
GET /api/gbs/banking/v4.0/accounts/{accountId}/parent
```

Request parameters:

- `accountId` – required; ID of the account

Example response:

```json
{
  "accountId": "14527670",
  "iban": "IT00A0000000000000000000000",
  "status": "ACTIVE"
}
```

Response parameters:

- `accountId` – ID of the main account
- `iban` – IBAN of the account
- `status` – account status

---

## Get Parent Account Transactions

Returns the list of transactions for the main account.

Example request:

```text
GET /api/gbs/banking/v4.0/accounts/{accountId}/parent/transactions
```

Request parameters:

- `accountId` – required; ID of the account

Example response:

```json
{
  "transactions": [
    {
      "transactionId": "987654321",
      "amount": 150,
      "currency": "EUR",
      "date": "2024-02-01",
      "description": "Payment received"
    }
  ]
}
```

Response parameters:

- `transactions` – list of transactions
- `transactionId` – transaction identifier
- `amount` – amount
- `currency` – currency
- `date` – transaction date
- `description` – description