# Virtual bank accounts

Upvest offers virtual bank accounts within our Investment API.

Please note that this functionality is only available on request. Upvest will need to activate it for you after consultation.

Once enabled, you can create virtual bank account(s) manually for each of your account groups.

## Prerequisites

- Upvest must have activated this feature for you.
- To set up a virtual bank account, you need to provide all the information required for the creation.


## Create a virtual bank account

The creation is performed with the following request:

**POST** [`/payments/virtual_bank_accounts`](/api/virtual-bank-accounts/create_virtual_bank_account)

**Example request**


```json
{
  "account_group_id": "f874a64a-ceaa-42b2-b59a-39d4f62166fb",
  "name": "Max's Virtual Bank Account"
}
```

**Example response**


```json
{
  "id": "22913092-0484-42e9-9273-9ffd6dfd0b13",
  "created_at": "2021-07-21T14:10:00.00Z",
  "account_group_id": "d1354aad-6da7-4da7-aaa1-e00ebfd3240d",
  "name": "Max's Virtual Bank Account",
  "owner": {
    "name": "Max Musterman"
  },
  "identification": {
    "swift": {
      "iban": "DE89000000000000000000",
      "bic": "ABCDEXXX"
    }
  }
}
```

Additionally, you will be notified via webhook upon creation. You will receive a corresponding [webhook](#Webhooks) when the virtual bank account is created for an account group.

## Get a virtual bank account by ID

To retrieve a virtual bank account specified by its ID, submit the following request:

**GET** [`/payments/virtual_bank_accounts/{virtual_bank_account_id}`](/api/virtual-bank-accounts/retrieve_virtual_bank_account)

**Example response**


```json
{
  "id": "22913092-0484-42e9-9273-9ffd6dfd0b13",
  "created_at": "2021-07-21T14:10:00.00Z",
  "account_group_id": "d1354aad-6da7-4da7-aaa1-e00ebfd3240d",
  "name": "Max's Virtual Bank Account",
  "owner": {
    "name": "Max Musterman"
  },
  "identification": {
    "swift": {
      "iban": "DE89000000000000000000",
      "bic": "ABCDEXXX"
    }
  }
}
```

## List virtual bank accounts

To retrieve the list of virtual bank accounts of a specific account group, call:

**GET** [`/account_groups/{account_group_id}/payments/virtual_bank_accounts`](/api/virtual-bank-accounts/list_virtual_bank_accounts)

**Example response**


```json
{
  "meta": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "total_count": 1,
    "sort": "id",
    "order": "ASC"
  },
  "data": [
    {
      "id": "22913092-0484-42e9-9273-9ffd6dfd0b13",
      "created_at": "2021-07-21T14:10:00.00Z",
      "account_group_id": "d1354aad-6da7-4da7-aaa1-e00ebfd3240d",
      "name": "Max's Virtual Bank Account",
      "owner": {
        "name": "Max Musterman"
      },
      "identification": {
        "swift": {
          "iban": "DE89000000000000000000",
          "bic": "ABCDEXXX"
        }
      }
    }
  ]
}
```

## Webhooks

You will receive a webhook notification when a virtual bank account is created.

- `VIRTUAL_BANK_ACCOUNT.CREATED`


**Example webhook**


```json
{
  "id": "8962b496-8d42-4560-bfab-10490dd1a721",
  "created_at": "2021-07-21T14:10:00.00Z",
  "type": "VIRTUAL_BANK_ACCOUNT.CREATED",
  "object": {
    "id": "22913092-0484-42e9-9273-9ffd6dfd0b13",
    "created_at": "2021-07-21T14:10:00.00Z",
    "account_group_id": "d1354aad-6da7-4da7-aaa1-e00ebfd3240d",
    "name": "Max's Virtual Bank Account",
    "owner": {
      "name": "Max Musterman"
    },
    "identification": {
      "swift": {
        "iban": "DE89000000000000000000",
        "bic": "ABCDEXXX"
      }
    }
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}
```