A real account is a physical account held with ClearBank and can be used to send and/or receive payments.

Before creating an account, please ensure that you know which account type you need to create. If you are unsure, please get in touch.

The balance of a real account is also held by ClearBank and can be viewed via the Institution portal and the ClearBank API. Real accounts are reconciled for you by ClearBank.

Get all accounts (real)

get/v3/Accounts

Gets all accounts associated with your institution.

All accounts are returned except those which have been disabled or where the account is a virtual account.

Parameters

pageNumber integer, query
The page number to control returned results into manageable sets. Default if not supplied: 1.
pageSize integer, query
The page size to control returned results into manageable sets. Default if not supplied: 50.
Authorization string, header, Required
Your API Token, retrieved from the web portal.

Response (application/json)

200 Success
400 Bad Request
500 Server Error
503 Server Error

Success

{
  "accounts": [
    {
      "id": "string",
      "name": "string",
      "label": "string",
      "type": "CACC",
      "currency": [
        "AED"
      ],
      "balances": [
        {
          "name": "string",
          "amount": 0,
          "currency": "AED",
          "status": "CLBD",
          "lastCommittedTransaction": "string"
        }
      ],
      "minimumBalance": {
        "name": "string",
        "amount": 0,
        "currency": "AED",
        "status": "CLBD",
        "lastCommittedTransaction": "string"
      },
      "status": "NotProvided",
      "statusReason": "NotProvided",
      "iban": "string",
      "bban": "string",
      "upic": "string",
      "cuid": "string"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Create an account (real)

post/v3/Accounts

Creates an account with the specified name.

Currently, this endpoint only supports the creation of current accounts.
AccountName must: not be null, only white space, only contain letters, numbers and the following special characters: - ,.
This endpoint uses the X-Request-Id as a duplicate check.

Parameters

Authorization string, header, Required
Your API Token, retrieved from the web 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.

Request Payload (application/json)

accountName string, Required
The friendly name that should be associated with the account.
Minimum length
1
Maximum length
70
Pattern
^[a-zA-Z0-9\- ,.]*$
owner object, Required
Set of elements used to identify a person or an organisation.
sortCode string, Required
The sort code these accounts should be created under.
Pattern
^\d{6}$
usageType string
The type of funds the account will hold. Default if not supplied: YourFunds.
Enum array
YourFunds, SegregatedDesignated, SegregatedPooled

request

{
  "accountName": "string",
  "owner": {
    "name": "string"
  },
  "sortCode": "string",
  "usageType": "YourFunds"
}

Code copied

Response (application/json)

201 Success
400 Bad Request
403 Forbidden
409 Conflict
500 Server Error
503 Server Error

Success

{
  "account": {
    "id": "string",
    "name": "string",
    "label": "string",
    "type": "CACC",
    "currency": [
      "AED"
    ],
    "balances": [
      {
        "name": "string",
        "amount": 0,
        "currency": "AED",
        "status": "CLBD",
        "lastCommittedTransaction": "string"
      }
    ],
    "minimumBalance": {
      "name": "string",
      "amount": 0,
      "currency": "AED",
      "status": "CLBD",
      "lastCommittedTransaction": "string"
    },
    "status": "NotProvided",
    "statusReason": "NotProvided",
    "iban": "string",
    "bban": "string",
    "upic": "string",
    "cuid": "string"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Associated Webhooks

Account Created webhook

This webhook confirms the account has been created.

Request body

{
    "Type":"AccountCreated",
    "Version":1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`AccountId`	Account identifier used to uniquely identify the account. Type: `string` Format: `GUID`
`AccountName`	Name of the account. Type: `string` Max. length: `128`
`AccountHolderLabel`	The account description. Type: `string` Max. length: `100`
`AccountIdentifiers`	Account identifier details. Type: `object` `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`TimestampCreated`	The date and time the account was created. Type: `string` Time Zone: `UTC` Format: `DateTime`
`AccountType`	Type of account. Type: `string` Examples: `CurrentAccount`, `DepositAccount`, `ControlAccount`, `SegregatedClientAccount`, `InstitutionAccount`
`Nonce`	Cryptographically secure number generated by ClearBank® for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example account created webhook request body

{
    "Type":"AccountCreated",
    "Version":1,
    "Payload":{
        "AccountId":"56de3483-a569-42eb-90cc-acf59661356f",
        "AccountName":"JOHN DOE",
        "AccountHolderLabel":"JOHN DOE",
        "AccountIdentifiers":{
            "IBAN":"GB00CUBK11223312345678",
            "BBAN":"CUBK11223312345678"
        },
        "TimestampCreated":"2018-07-19T13:31:30.8789344Z",
        "AccountType":"CurrentAccount"
    },
    "Nonce":1082937278
}

Example webhook response

{
    "Nonce": 1082937278
}

Get information for an account (real)

get/v3/Accounts/{accountId}

Gets a detailed view of an account.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v3/Accounts.
Authorization string, header, Required
Your API Token, retrieved from the web portal.

Response (application/json)

200 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "account": {
    "id": "string",
    "name": "string",
    "label": "string",
    "type": "CACC",
    "currency": [
      "AED"
    ],
    "balances": [
      {
        "name": "string",
        "amount": 0,
        "currency": "AED",
        "status": "CLBD",
        "lastCommittedTransaction": "string"
      }
    ],
    "minimumBalance": {
      "name": "string",
      "amount": 0,
      "currency": "AED",
      "status": "CLBD",
      "lastCommittedTransaction": "string"
    },
    "status": "NotProvided",
    "statusReason": "NotProvided",
    "iban": "string",
    "bban": "string",
    "upic": "string",
    "cuid": "string"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Amend an account (real)

patch/v1/Accounts/{accountId}

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

Parameters

accountId string, path, Required
The unique identifier for the account.
Authorization string, header, Required
Your API Token, retrieved from the web 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.

Request Payload (application/json)

status string
Current status of the account. Valid options include Not Provided, Enabled, Closed, Suspended.
Enum array
NotProvided, Enabled, Closed, Suspended
statusReason string
Reason that the account is Closed or Suspended. Valid options include NotProvided, AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, Other.
Enum array
NotProvided, AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, Other
ownerName string
The name used to identify the legal owner of the account.
Minimum length
0
Maximum length
70
Pattern
^[^<!&|$*;^%_>`#@="~\[\]{}\\]*$
legalOwnerType string
Nature of funds held in the account. Valid options include: Personal, Business.
Enum array
Personal, Business
relationshipType string
Operating nature of the account. Valid options include Single, Joint. If legalOwnerType is Business, then the relationshipType cannot be Joint.
Enum array
Single, Joint
minimumBalance number
The minimum allowable balance of the account (example: -£1000). Note that you must send a negative number to create an overdraft. This field can only be used if your organisation is an embedded banking client with an overdraft agreement in place; otherwise the request will be rejected.

request

{
  "status": "NotProvided",
  "statusReason": "NotProvided",
  "ownerName": "string",
  "legalOwnerType": "Personal",
  "relationshipType": "Single",
  "minimumBalance": 0
}

Code copied

Response (application/json)

204 Success
400 Bad Request
403 Forbidden
409 Conflict
500 Server Error
503 Server Error

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Conflict

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

A virtual account held with ClearBank is a shadow account which should mirror an account held on your platform. Each virtual account is linked to a real account held at ClearBank. You can use a virtual account to send and/or receive payments by means of its association with this real account. The responsibility of managing and reconciling virtual accounts rests with you, which gives you complete control of such accounts.

Get accounts (virtual)

get/v1/Accounts/Virtual

Lists all of the virtual accounts belonging to an institution.

All virtual accounts are returned including those which have been disabled. A status field is available.

Parameters

pageNumber integer, query
The page number to control returned results into manageable sets. Default if not supplied: 1.
pageSize integer, query
The page size to control returned results into manageable sets. Default if not supplied: 50.
Authorization string, header, Required
Your API Token, retrieved from the web portal.

Response (application/json)

200 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "accounts": [
    {
      "id": "string",
      "name": "string",
      "type": "CACC",
      "status": "Enabled",
      "currency": [
        "GBP"
      ],
      "iban": "string",
      "bban": "string",
      "upic": "string",
      "cuid": "string"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Create accounts (virtual)

post/v2/Accounts/{accountId}/Virtual

Creates a series of virtual accounts.

This endpoint uses accountIdentifier as a duplicate check.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v3/Accounts.
Authorization string, header, Required
Your API Token, retrieved from the web 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.

Request Payload (application/json)

virtualAccounts array, Required
The virtual accounts that should be created.

request

{
  "virtualAccounts": [
    {
      "ownerName": "string",
      "accountIdentifier": {
        "iban": "string",
        "bban": "string",
        "proprietaryIdentifier": "string",
        "externalIdentifier": "string"
      }
    }
  ]
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

This webhook confirms creation of a virtual account.

Version 3 has introduced the following new optional field:

ExternalIdentifier

The ExternalIdentifier field in both webhooks will show the externalId that you have specified instead of an account identifier (IBAN, BBAN or sort code and account number) at the time of creating a virtual account.

Request body

The request body consists of a DigitalSignature, Type,Version,Payload and Nonce. Payload parameters vary depending on the webhook. Webhook responses a 200 HTTP status code which includes a Nonce number in the body and your DigitalSignature.

{
    "Type":"VirtualAccountCreated",
    "Version":3,
    "Payload": {...},
    "OwnerName": ,
    "TimestampCreated": ,
    "Nonce":
}

Payload

Element	Description
`AccountId`	Required Unique identifier for the real account associated with the virtual account. Type: `string` Format:`GUID` Min. length: `1`
`VirtualAccountId`	Required Account identifier used to uniquely identify the virtual account. Type: `string` Format: `GUID` Min. length: `1`
`AccountIdentifiers`	Required Virtual account identifier details. Type: `object` `IBAN`: International Bank Account Number associated with the virtual account. Type: `string` pattern: `^([A-Z]{2})([0-9]{2})([A-Za-z]{4})([0-9]{6})([0-9]{8})$` Min. length: `0` Max. length: `140` `BBAN`: Basic Bank Account number associated with the virtual account. Type: `string` Pattern: `^([A-Za-z]{4})([0-9]{6})([0-9]{8})$` Min. length: `0` Max. length: `140`
`ExternalIdentifier`	Optional Unique identifier specified at the time of creating a virtual account. Type: `string` Min. length: `0` Max. length: `50`
`OwnerName`	Optional Name for the owner of the virtual account. Type: `string` Min. length: `0` Max. length: `140`
`TimestampCreated`	Required The date and time the virtual account was created. Type: `string` Time Zone: `UTC` Format: `DateTime` Min. length: `1`
`Nonce`	Cryptographically secure number generated by ClearBank® for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example virtual account created webhook request body

{
    "Type":"VirtualAccountCreated",
    "Version":3,
    "Payload":{
        "AccountId":"4fbe973b-2f30-45f0-b9e4-a488dd275861",
        "VirtualAccountId":"b3c93a68-5992-4f83-99d5-f13405fd2d90",
        "AccountIdentifier":{
            "Iban":"GB00CUBK22002243218765",
            "Bban":"CUBK22002243218765",
            "ExternalIdentifier":"98765432abcdefg"
        },
        "OwnerName":"Joe Brown",
        "TimestampCreated":"2018-07-19T13:44:56.7366698Z"
    },
    "Nonce":1623028327
}

Example webhook response

{
    "Nonce": 1623028327
}

This webhook confirms a virtual account creation failure.

Version 3 has introduced the following new optional field:

ExternalIdentifier

Request body

The request body consists of a DigitalSignature, Type,Version,Payload and Nonce. Payload parameters vary depending on the webhook. Webhook responses a 200 HTTP status code which includes a Nonce number in the body and your DigitalSignature.

{
    "Type":"VirtualAccountCreationFailed",
    "Version":3,
    "Payload": {...},
    "Errors":{...},
    "OwnerName": ,
    "Nonce":
}

Payload

Element	Description
`AccountId`	Required Unique identifier for the real account associated with the virtual account. Type: `string` Format:`GUID` Min. length: `1`
`VirtualAccountId`	Required Account identifier used to uniquely identify the virtual account. Type: `string` Format: `GUID` Min. length: `1`
`AccountIdentifiers`	Required Virtual account identifier details. Type: `object` `IBAN`: International Bank Account Number associated with the virtual account. Type: `string` pattern: `^([A-Z]{2})([0-9]{2})([A-Za-z]{4})([0-9]{6})([0-9]{8})$` Min. length: `0` Max. length: `140` `BBAN`: Basic Bank Account number associated with the virtual account. Type: `string` Pattern: `^([A-Za-z]{4})([0-9]{6})([0-9]{8})$` Min. length: `0` Max. length: `140`
`ExternalIdentifier`	Optional Unique identifier specified at the time of creating a virtual account. Type: `string` Min. length: `0` Max. length: `50`
`Errors`	Required Error(s) which caused the virtual account creation to fail. Type: `Object` One or more errors that occurred during the processing of the request: Additional Properties Type: `string` An error code and error explanation will be provided as a Key value pair These are some examples of error codes: `AccountIban`, `AccountIbanSortCode`, `AccountIbanAccountNumber`, `AccountBban`, `AccountBbanSortCode`, `AccountBbanAccountNumber`, `AccountIdentifiers`, `AccountName`, `AccountHolderLabel`, `AccountIbanBankCode`, `AccountBbanBankCode`, `ClientMoneyAccountIdMissing`, `ExternalVirtualAccountIdNotUnique`, `ExternalVirtualAccountId`, `VirtualAccountIdMissing`, `AccountModulusFailed`, `SortCodeDoesNotBelongToInstitution`, `SortCodeTypeIsIncorrect`
`OwnerName`	Optional Name for the owner of the virtual account. Type: `string` Min. length: `0` Max. length: `140`
`Timestamp`	Required The date and time the virtual account was created. Type: `string` Time Zone: `UTC` Format: `DateTime` Min. length: `1`
`Nonce`	Cryptographically secure number generated by ClearBank® for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example virtual account creation failed webhook request body

{
    "Type":"VirtualAccountCreationFailed",
    "Version":3,
    "Payload":{
        "AccountId":"e2fb8de0-675d-479a-8b0f-596bc6f52a61",
        "VirtualAccountId":"ba393cc1-8f58-4542-b72f-db62910dce0e",
        "AccountIdentifier":{
            "Iban":"GB00CUBK22002243218765",
            "Bban":"CUBK22002243218765",
            "ExternalIdentifier":"98765432abcdefg"
        },
        "Errors":{
            "AccountIbanSortCode":"Invalid Sort Code"
        },
        "OwnerName":"Joe Brown",
        "Timestamp":"2018-07-19T13:44:56.7406379Z"
    },
    "Nonce":482504208
}

Example webhook response

{
    "Nonce": 482504208
}

Get all virtual accounts for a real account

get/v2/Accounts/{accountId}/Virtual

Lists all of the virtual accounts belonging to a given account.

All virtual accounts are returned including those which have been disabled. A Status field is available.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v3/Accounts.
pageNumber integer, query
The page number to control returned results into manageable sets. Default if not supplied: 1.
pageSize integer, query
The page size to control returned results into manageable sets. Default if not supplied: 50.
Authorization string, header, Required
Your API Token, retrieved from the web portal.

Response (application/json)

200 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "accounts": [
    {
      "id": "string",
      "name": "string",
      "label": "string",
      "type": "CACC",
      "status": "Enabled",
      "currency": [
        "AED"
      ],
      "iban": "string",
      "bban": "string",
      "upic": "string",
      "cuid": "string"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Get information for an account (virtual)

get/v2/Accounts/{accountId}/Virtual/{virtualAccountId}

Gets a specific virtual account.

Parameters

accountId string, path, Required
The account identifier.
virtualAccountId string, path, Required
The virtual account identifier.
Authorization string, header, Required
Your API Token, retrieved from the web portal.

Response (application/json)

200 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "account": {
    "id": "string",
    "name": "string",
    "label": "string",
    "type": "CACC",
    "status": "Enabled",
    "currency": [
      "AED"
    ],
    "iban": "string",
    "bban": "string",
    "upic": "string",
    "cuid": "string"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Not Found

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Amend an account (virtual)

patch/v1/Accounts/{accountId}/Virtual/{virtualAccountId}

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

Parameters

accountId string, path, Required
The account identifier.
virtualAccountId string, path, Required
The virtual account identifier.
Authorization string, header, Required
Your API Token, retrieved from the web 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.

Request Payload (application/json)

ownerName string
The name used to identify the legal owner of the virtual account.
Minimum length
0
Maximum length
70
Pattern
^[^<!&|$*;^%_>`#@="~\[\]{}\\]*$
legalOwnerType string
Nature of funds held in the virtual account. Valid options include: Personal, Business.
Enum array
Personal, Business
relationshipType string
Operating nature of the virtual account. Valid options include Single, Joint. If legalOwnerType is Business, then the relationship type cannot be Joint.
Enum array
Single, Joint

request

{
  "ownerName": "string",
  "legalOwnerType": "Personal",
  "relationshipType": "Single"
}

Code copied

Response (application/json)

204 Success
400 Bad Request
403 Forbidden
404 Not Found
409 Conflict
500 Server Error
503 Server Error

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Disable an account (virtual)

delete/v1/Accounts/{accountId}/Virtual/{virtualAccountId}

Disables the virtual account that belongs to the given account

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
virtualAccountId string, path, Required
The unique identifier for the virtual account. This can be retrieved from GET /v1/Accounts/{accountId}/Virtual
Authorization string, header, Required
Your API Token, retrieved from the web portal.
X-Request-Id string, header, Required
A unique identifier for the request.

Response (application/json)

204 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Manage sterling accounts

Real GBP accounts

Get all accounts (real)

Parameters

Response (application/json)

Create an account (real)

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Get information for an account (real)

Parameters

Response (application/json)

Amend an account (real)

Parameters

Request Payload (application/json)

Response (application/json)

Virtual GBP accounts

Get accounts (virtual)

Parameters

Response (application/json)

Create accounts (virtual)

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Get all virtual accounts for a real account

Parameters

Response (application/json)

Get information for an account (virtual)

Parameters

Response (application/json)

Amend an account (virtual)

Parameters

Request Payload (application/json)

Response (application/json)

Disable an account (virtual)

Parameters

Response (application/json)