---
title: "Create a settlement account"
method: POST
path: "/virtual-accounts"
tags: ["Settlement Accounts"]
---

# Create a settlement account

`POST /virtual-accounts`

The `POST /virtual-accounts` endpoint creates a settlement account.

## Request body

- CreateVirtualAccountRequest — Contains the request payload to create a settlement account.
  - `accountNickName` string — The alias name that identifies the settlement account. May contain up to 50 characters including letters, numbers, hyphens, underscores, and spaces.
  - `currency` string, required — The <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank">ISO 4217</a> three letter currency code.
  - `onBehalfOfId` string — The id of the ultimate client on whose behalf the account is created. If the account is created on behalf of a sub-TPP, this field will contain the sub-TPP `referenceId`. This field is mandatory for unregulated TPPs.
  - `country` string, required — Two-letter country code in upper case (ISO 3166-1 alpha-2).

## Response `200`

Successful response

- CreateVirtualAccountResponse — Contains the response to the submitted request.
  - `virtualAccount` VirtualAccount
    - `accountId` string — The system-generated, unique id which specifies the settlement account.
    - `accountName` string — The name of this account.
    - `accountNickName` string — The alias name that identifies the settlement account.
    - `accountNumber` string — The unique identifier for the bank account in the UK or Ireland.
    - `availableBalance` string — The available account balance at the time of the query. For example, the previous day's closing balance +/- transactions during the day, and any overdraft facilities.
    - `bic` string — The Business Identifier Code (BIC), <a href="https://www.iso.org/standard/84108.html" target="_blank">ISO 9362</a>, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long."
    - `bookedBalance` string — The account balance pending clearance, which may include uncleared items and any transactions yet to settle.
    - `clearedBalance` string — The cash balance in an account that can be immediately withdrawn or used in financial transactions. Until funds have cleared, they're considered to be pending and customers are unable to use them in transactions.
    - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2).
    - `createdDateTime` string, string — The date this account was created (in <a href="https://www.iso.org/iso-8601-date-and-time-format.html" target="_blank">ISO 8601</a> format).
    - `currency` string — The <a href="https://www.iso.org/iso-4217-currency-codes.html" target="_blank">ISO 4217</a> three letter currency code.
    - `iban` string — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters.
    - `sortCode` string — The number assigned to a branch of a bank, typically containing six digits and most commonly used in the UK and Ireland.
    - `status` 'INVALID' | 'ACTIVE' | 'CLOSED' | 'BLOCKED' | 'CLIENT_BLOCKED'
    - `updatedDateTime` string, string — The date and time this account was last updated (in <a href="https://www.iso.org/iso-8601-date-and-time-format.html" target="_blank">ISO 8601</a> format).
    - `onBehalfOfId` string — The id of the ultimate client on whose behalf the account is created. If the account is created on behalf of a sub-TPP, this field will contain the sub-TPP `referenceId`. This field is mandatory for unregulated TPPs.
    - `providerAccountId` string — The id of this account at the underlying banking provider (e.g. Modulr). Use this to correlate this account with the `providerAccountId` on virtual account webhook events.

## Other responses

- `400` — The client specified an invalid argument
- `401` — The authorization information is missing or invalid
- `403` — Permission to access this endpoint is denied
- `404` — The requested entity, such as a TPP, was not found
- `429` — Too many requests
- `500` — An unexpected or internal server error
- `501` — The operation was not implemented
- `503` — Service is unavailable
- `504` — Gateway has timed out

---

[API](https://skmtc.net/token/apis/token-io-s-open-banking-api-for-tpps.md) · [All operations](https://skmtc.net/token/apis/token-io-s-open-banking-api-for-tpps/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/token/token-io-s-open-banking-api-for-tpps/revisions/08c7d0c9ce60/schema)