Skip to content
Documentation
/
/
/
Virtual Bank Accounts

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

  • Authentication scopes — payments:admin, reference_accounts:admin

    For more information, refer to Authentication scopes.

Before creating virtual bank accounts, ensure you have:

  • Webhook handler ready — Set up a webhook endpoint to listen for virtual account creation events.

    For more information, refer to Implementing webhooks.

  • Upvest must have activated this feature for you

  • 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

Example request

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

Example response

{
  "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 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}

Example response

{
  "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

Example response

{
  "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

Recommended: Use webhooks to track virtual account creation

Set up a webhook listener for VIRTUAL_BANK_ACCOUNT.CREATED to be notified immediately when a virtual bank account is provisioned. Do not poll the virtual account status endpoint.

For more information, refer to Payment webhook events

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

  • VIRTUAL_BANK_ACCOUNT.CREATED

Example webhook

{
  "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"
}