Accounts

Real Accounts

A real account is a physical account held with ClearBank® and can be used to send and/or receive payments. 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

get/v2/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
  • 403 Forbidden
  • 500 Server Error
  • 503 Server Error

Success

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

Create an account

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: - ,.

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

  • 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

  • usageType string, Required

    The specified usage type for the request

    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": [
"ALL"
],
"balances": [
{
"name": "string",
"amount": 0,
"currency": "ALL",
"status": "CLBD",
"lastCommittedTransaction": "string"
}
],
"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

Get information for an account

get/v2/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 /v1/Accounts

  • Authorization string, header, Required

    Your API Token, retrieved from the web portal

Response (application/json)

  • 200 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": [
"ALL"
],
"balances": [
{
"name": "string",
"amount": 0,
"currency": "ALL",
"status": "CLBD",
"lastCommittedTransaction": "string"
}
],
"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

Change the status of an account

patch/v1/Accounts/{accountId}

Amends properties of an account

Currently supports changing the status of an 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,

    The status of the account.

    NotProvided, Enabled, Closed, Suspended
  • statusReason string,

    The account status reason

    NotProvided, AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, Other

request

{
"status": "NotProvided",
"statusReason": "NotProvided"
}
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

Virtual Accounts

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 all virtual accounts

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: ClearBank.FI.API.Versions.V1.Controllers.BaseController.DefaultPageNumber

  • pageSize integer, query

    The page size to control returned results into manageable sets. Default if not supplied: ClearBank.FI.API.Versions.V1.Controllers.BaseController.DefaultPageSize

  • 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": [
"ALL"
],
"iban": "string",
"bban": "string",
"upic": "string",
"cuid": "string"
}
],
"halLinks": [
{
"name": "string",
"href": "string",
"templated": true
}
]
}
Code copied

Create virtual accounts

post/v2/Accounts/{accountId}/Virtual

Creates a series of virtual accounts

Parameters

  • accountId string, path, Required

    The unique identifier for the account. This can be retrieved from GET /v1/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

Associated Webhooks

Get information for a virtual account

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": [
"ALL"
],
"iban": "string",
"bban": "string",
"upic": "string",
"cuid": "string"
},
"halLinks": [
{
"name": "string",
"href": "string",
"templated": true
}
]
}
Code copied

Update owner for a virtual account

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

Requests update of a 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, Required

    Owner name

request

{
"ownerName": "string"
}
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 a virtual account

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