ClearBank

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

This endpoint uses the X-Request-Id as a duplicate check and to ensure the request is idempotent.

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. If not specified, usage type will default to 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": [
      "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

Amend the properties of an existing account

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 for why the current status of 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, relationshipType cannot be Joint.

    Enum array
    Single, Joint

request

{
  "status": "NotProvided",
  "statusReason": "NotProvided",
  "ownerName": "string",
  "legalOwnerType": "Personal",
  "relationshipType": "Single"
}
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

This endpoint uses accountIdentifier as a duplicate check and to ensure the request is idempotent.

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 all virtual accounts for a specific 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 /v1/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": [
        "ALL"
      ],
      "iban": "string",
      "bban": "string",
      "upic": "string",
      "cuid": "string"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}
Code copied

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

Amend the properties of an existing virtual account

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, relationshipType 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 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