Manage virtual accounts

Virtual accounts are publicly addressable accounts with their own IBAN. Also known as shadow accounts, virtual accounts are linked to real accounts and are used to separate out funds held in real accounts for the purposes of improved reconciliation and liquidity management. The responsibility of managing and reconciling virtual accounts rests with you, giving you complete control of such accounts.

Virtual accounts are only compatible with General Segregated Accounts. Virtual accounts can be created, suspended or activated, and closed via our API.

To comply with the Funds Transfer Regulation, it is important that the naming of virtual accounts reflects the legal name of the customer.

Create an account (virtual)

post/mccy/v1/VirtualAccounts

This endpoint is used to create a new virtual account.

Parameters

Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

accountId string, Required
Unique identifier for the real account associated with the virtual account.
virtualAccount object, Required
Set of elements used to identify a virtual account.

request

{
  "accountId": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "virtualAccount": {
    "owner": "James Smith",
    "identifiers": [
      {
        "identifier": "GB29CLRB40391731926000",
        "kind": "Iban"
      }
    ]
  }
}

Code copied

Response (application/json)

201 Created
400 Bad Request
404 Not Found
422 Client Error

Created

{
  "id": "3fb8a2ce-064a-4de6-8e92-def9fce8772c",
  "accountId": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "owner": "James Smith",
  "status": "Active",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "statusReason": "AccountHolderBankrupt",
  "statusInformation": "Received documentation"
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Found

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Client Error

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Multi-currency Virtual Account Created webhook

This webhook confirms that the multi-currency virtual account has been created.

Request body

{
    "Type":"Accounts.VirtualAccountCreated",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`VirtualAccountId`	Required Account identifier used to uniquely identify the virtual account. Type: `string` Min. Length: `1` Format: `GUID`
`AccountId`	Required Unique identifier for the real account associated with the virtual account. Type: `string` Min. Length: `1` Format: `GUID`
`BatchId`	Required Unique batch identifier specified while creating a batch of virtual accounts. Type: `string` Min. Length: `1` Format: `GUID`
`Owner`	Required The name used to identify the legal owner of the virtual account. Type: `string` Min. Length: `1` Max. Length: `140`
`Status`	Required The current status of the virtual account. Type: `string` Examples: `Active`, `Suspended`, `Closed`
`Identifiers`	Required List of identifiers. It is an array of objects with an Identifier and Kind. Type: `array` `Identifier` Unique virtual account identifier value that corresponds to the specified virtual account identifier kind. Type: `string` Min. Length: `1` Max. Length: `50` `Kind` The kind of virtual account identifier provided to uniquely identify the virtual account. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time the virtual account was created. Time in UTC. Type: `string` Format: `date-time`

Example virtual account created webhook request body

{
    "Type":"Accounts.VirtualAccountCreated",
    "Version":1,
    "InstitutionId":"4befdd75-5297-44b3-b70f-234d8a525dd2",
    "Payload":{
        "VirtualAccountId":"b3c93a68-5992-4f83-99d5-f13405fd2d90",
        "AccountId":"d55149f7-f052-49cc-865b-7446b4fb05f5",
        "BatchId":"21d70e60-61f0-4bfb-bd22-a460216947b4",
        "Owner":"Joe Brown",
        "Status":"Active",
        "Identifiers":[
            {
                "Identifier":"GB88BARC20040425385198",
                "Kind":"IBAN"
            }
        ],
        "TimestampCreated":"2021-04-08T12:00:00.0000000"
    },
    "Nonce":748364091
}

Example webhook response

{
    "Nonce": 748364091
}

Get information for an account (virtual)

get/mccy/v1/VirtualAccounts/{virtualAccountId}

This endpoint is used to retrieve details related to a virtual account.

Parameters

Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Generated from your HTTP METHOD, Query Path, X-Request-Id, and X-Request-Time values.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.
X-Request-Time string, header, Required
The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.
virtualAccountId string, path, Required
The unique identifier for the virtual account.

Response (application/json)

200 OK
400 Bad Request
404 Not Found

OK

{
  "id": "3fb8a2ce-064a-4de6-8e92-def9fce8772c",
  "accountId": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "owner": "James Smith",
  "status": "Active",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "statusReason": "AccountHolderBankrupt",
  "statusInformation": "Received documentation"
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Found

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Amend the properties of an account (virtual)

patch/mccy/v1/VirtualAccounts/{virtualAccountId}

This endpoint is used to amend the properties of an existing virtual account.

Parameters

virtualAccountId string, path, Required
The unique identifier for the virtual account.
Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

owner string, Required
The name used to identify the legal owner of the virtual account.
Minimum length
1
Maximum length
140

request

{
  "owner": "James Smith-Jones"
}

Code copied

Response (application/json)

200 OK
400 Bad Request
403 Forbidden
404 Not Found

OK

{
  "id": "3fb8a2ce-064a-4de6-8e92-def9fce8772c",
  "accountId": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "owner": "James Smith",
  "status": "Active",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "statusReason": "AccountHolderBankrupt",
  "statusInformation": "Received documentation"
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Forbidden

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Found

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Multi-currency Virtual Account Updated webhook

This webhook confirms that the multi-currency virtual account has been updated.

Request body

{
    "Type":"Accounts.VirtualAccountUpdated",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`VirtualAccountId`	Required Account identifier used to uniquely identify the virtual account. Type: `string` Min. Length: `1` Format: `GUID`
`AccountId`	Required Unique identifier for the real account associated with the virtual account. Type: `string` Min. Length: `1` Format: `GUID`
`Owner`	Required The name used to identify the legal owner of the virtual account. Type: `string` Min. Length: `1` Max. Length: `140`
`Status`	Required The current status of the virtual account. Type: `string` Examples: `Active`, `Suspended`, `Closed`
`Identifiers`	Required List of identifiers. It is an array of objects with an Identifier and Kind. Type: `array` `Identifier` Unique virtual account identifier value that corresponds to the specified virtual account identifier kind. Type: `string` Min. Length: `1` Max. Length: `50` `Kind` The kind of virtual account identifier provided to uniquely identify the virtual account. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time the virtual account was created. Time in UTC. Type: `string` Format: `date-time`
`TimestampModified`	Required Date and time the virtual account was last modified. Time in UTC. Type: `string` Format: `date-time`
`StatusReason`	Optional Reason for changing the current status of the virtual account. Valid options include: AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateAccount, FinancialCrime, FraudConfirmed, FraudFirstParty, FraudThirdParty, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute, Other. Type: `string`
`StatusInformation`	Optional Additional information to support the specified status reason. Type: `string` Min. Length: `0` Max. Length: `100`

Example virtual account updated webhook request body

{
    "Type":"Accounts.VirtualAccountUpdated",
    "Version":1,
    "Payload":{
        "VirtualAccountId":"2a77e175-9bf2-4e0b-a8ca-4cee0610cf26",
        "AccountId":"78b208f0-498e-4412-b462-68beadb6e555",
        "Owner":"E2E Financial Services Limited",
        "Status":"Suspended",
        "Identifiers":[
            {
                "Identifier":"GB43CLRB04040545703930",
                "Kind":"Iban"
            }
        ],
        "TimestampCreated":"2021-07-21T09:06:33.0628794Z",
        "TimestampModified":"2021-07-21T10:00:45.3113241Z",
        "StatusReason":AccountSwitched,
        "StatusInformation":null
    },
    "Nonce":177103143
}

Example webhook response

{
    "Nonce": 177103143
}

Update the status of an account (virtual)

patch/mccy/v1/VirtualAccounts/{virtualAccountId}/status

This endpoint is used to update the status of an existing virtual account.

Parameters

virtualAccountId string, path, Required
The unique identifier for the virtual account.
Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

status string, Required
Desired status of the virtual account.
Enum array
Active, Suspended
statusReason string
Reason to support the desired status of the virtual account.
Enum array
AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateAccount, FinancialCrime, FraudConfirmed, FraudFirstParty, FraudThirdParty, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute, Other
information string
Additional information to support the specified status reason.
Minimum length
0
Maximum length
100

request

{
  "status": "Suspended",
  "statusReason": "FinancialCrime",
  "information": "Suspected fraudulent activity"
}

Code copied

Response (application/json)

200 OK
400 Bad Request
404 Not Found

OK

{
  "id": "3fb8a2ce-064a-4de6-8e92-def9fce8772c",
  "accountId": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "owner": "James Smith",
  "status": "Active",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "statusReason": "AccountHolderBankrupt",
  "statusInformation": "Received documentation"
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Found

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Multi-currency Virtual Account Updated webhook

Close an account (virtual)

delete/mccy/v1/VirtualAccounts/{virtualAccountId}

This endpoint is used to close an existing virtual account. Once a virtual account has been closed, it cannot be reopened.

Parameters

virtualAccountId string, path, Required
The unique identifier for the virtual account.
accountCloseReason string, query
Reason for why the account is being closed. Available options include: Other, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DuplicateAccount.
Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Generated from your HTTP METHOD, Query Path, X-Request-Id, and X-Request-Time values.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.
X-Request-Time string, header, Required
The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

Response (application/json)

204 No Content
404 Not Found
422 Client Error

Not Found

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Client Error

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Multi-currency Virtual Account Updated webhook