Manage real accounts

A real 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.

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

GBP payments to and from a European account are not allowed and would be rejected and returned automatically. For more information about currencies supported by ClearBank accounts, please speak to your Client Director.

To create and manage virtual accounts, refer to Manage accounts.

Create a new account (real)

post/mccy/v2/Accounts

This endpoint is used to create a new real multi-currency 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)

label string, Required
Friendly label for the account.
Minimum length
1
Maximum length
100
Pattern
^[^<>;"]*$
owner string, Required
The name used to identify the legal owner of the account.
Minimum length
1
Maximum length
140
Pattern
^[^<>;"]*$
kind string, Required
The type of funds the account will hold.
Enum array
YourFunds, GeneralSegregated, DesignatedSegregated, GeneralClient, DesignatedClient
currencies array, Required
Currencies supported by the account. This is the three-letter ISO currency code.
identifiers array
List of identifiers. If the account identifier of kind IBAN is not specified, it will be generated automatically.
bankIdentifierCode string, Required
The 8 or 11 character BIC under which the new account should be created. If using a UK BIC, a routing code will also be required.
routingCode string
Routing code for the new account. For example, 010203. When creating a UK account, a routing code (sort code) is required.
productId string
The product identifier used to determine the behaviour of the account. Only applicable for FSCS accounts.
customerId string
Unique identifier for the customer that the account is associated with. Only applicable for FSCS accounts.

request

{
  "label": "Mid tier asset funds",
  "owner": "Eco Bank",
  "kind": "GeneralSegregated",
  "currencies": [
    "string"
  ],
  "identifiers": [
    {
      "identifier": "string",
      "kind": "string"
    }
  ],
  "bankIdentifierCode": "CLRBGB99",
  "routingCode": "010203",
  "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "725a5f09-595a-4db1-946a-8330d423da34"
}

Code copied

Response (application/json)

201 Created
400 Bad Request
403 Forbidden
422 Client Error

Created

{
  "id": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "name": "Gen Seg Eco Bank",
  "label": "Mid tier asset funds",
  "owner": "Eco Bank",
  "kind": "GeneralSegregated",
  "currencies": [
    "string"
  ],
  "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "190e5d1d-7016-4efe-9988-3ebfecb21192",
  "identifiers": [
    {
      "identifier": "string",
      "kind": "string"
    }
  ],
  "status": "Active",
  "statusReason": "AccountHolderBankrupt",
  "statusInformation": "Received documentation",
  "type": "Customer"
}

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

Client Error

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

Code copied

Associated Webhooks

Multi-currency Account Created webhook

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

Request body

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

Payload

Element	Description
`AccountId`	Required Unique identifier for the account held with ClearBank. Type: `string` Format: `GUID`
`Name`	Required Name of the account. Type: `string` Min. Length: `1` Max. Length: `500`
`Label`	Required Friendly label for the account. Type: `string` Min. Length: `1` Max. Length: `100`
`Owner`	Required The name used to identify the legal owner of the account. Type: `string` Min. Length: `1` Max. Length: `140`
`Kind`	Required The type of funds the account will hold. Type: `string` Examples: `YourFunds`, `GeneralSegregated`, `DesignatedSegregated`, `GeneralClient`, `DesignatedClient`
`Currencies`	Required Currencies supported by the account. This is the three-letter ISO currency code. It is an array of strings. Type: `array` Min. Length: `3` Max. Length: `3` Pattern: `^[A-Z]{3}$`
`Status`	Required Current status of the account. Type: `string` Examples: `Active`, `Suspended`, `Closed`
`ProductId`	Optional The product identifier used to determine the behaviour of the account. Only applicable for FSCS accounts. Type: `string` Format: `GUID`
`CustomerId`	Optional Unique identifier for the customer that the account is associated with. Only applicable for FSCS accounts. Type: `string` Format: `GUID`
`Identifiers`	Required List of identifiers. It is an array of objects with an Identifier and Kind. Type: `array` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `50` `Kind` The kind of account identifier provided to uniquely identify the account. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time the account was created. Time in UTC. Type: `string` Format: `date-time`
`Type`	Required The type of account. Valid options include: Customer, Operating, MinimumMandatedBalance, Treasury, HeldSuspense, RepairSuspense, Institution. Type: `string`

Example account created webhook request body

{
    "InstitutionId":"faeac33e-e6ea-4712-991d-8c85d0eefda0",
    "Type":"Accounts.AccountCreated",
    "Version":1,
    "Payload":{
        "AccountId":"d55149f7-f052-49cc-865b-7446b4fb05f5",
        "Name":"JOHN DOE",
        "Label":"JOHN DOE",
        "Owner":"Financial Services Limited",
        "Kind":"YourFunds",
        "Currencies":[
            "EUR",
            "GBP"
        ],
        "Status":"Active",
        "ProductId":"f65f7f4b-b724-4692-b375-5a48513d732c",
        "CustomerId":"9e9ac5af-53bc-4b77-a5ac-bd001c866ce3",
        "Identifiers":[
            {
                "Identifier":"GB88BARC20040425385198",
                "Kind":"IBAN"
            }
        ],
        "TimestampCreated":"2021-04-08T12:00:00.0000000",
        "Type":"Customer"
    },
    "Nonce":748392098
}

Example webhook response

{
    "Nonce": 748392098
}

Get all accounts (real)

get/mccy/v1/Accounts

This endpoint is used to retrieve a list of all the accounts associated with your institution, excluding virtual accounts.

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

Response (application/json)

200 OK
400 Bad Request

OK

{
  "accounts": [
    {
      "id": "98efba88-c43e-41c5-9d47-0938f2fe7192",
      "name": "Gen Seg Eco Bank",
      "label": "Mid tier asset funds",
      "owner": "Eco Bank",
      "kind": "GeneralSegregated",
      "currencies": [
        "string"
      ],
      "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "customerId": "190e5d1d-7016-4efe-9988-3ebfecb21192",
      "identifiers": [
        {
          "identifier": "GB29CLRB40391731926000",
          "kind": "Iban"
        }
      ],
      "status": "Active",
      "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

Get information for an account (real)

get/mccy/v1/Accounts/{accountId}

This endpoint is used to retrieve details related to an account.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /mccy/v1/Accounts.
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)

200 OK
400 Bad Request
404 Not Found

OK

{
  "id": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "name": "Gen Seg Eco Bank",
  "label": "Mid tier asset funds",
  "owner": "Eco Bank",
  "kind": "GeneralSegregated",
  "currencies": [
    "string"
  ],
  "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "190e5d1d-7016-4efe-9988-3ebfecb21192",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "status": "Active",
  "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 (real)

patch/mccy/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. This can be retrieved from GET /mccy/v1/Accounts.
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)

label string, Required
Friendly label for the account.
Minimum length
1
Maximum length
100
owner string, Required
The name used to identify the legal owner of the account.
Minimum length
1
Maximum length
140

request

{
  "label": "High tier asset funds",
  "owner": "Eco Bank Ltd"
}

Code copied

Response (application/json)

200 OK
400 Bad Request
404 Not Found

OK

{
  "id": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "name": "Gen Seg Eco Bank",
  "label": "Mid tier asset funds",
  "owner": "Eco Bank",
  "kind": "GeneralSegregated",
  "currencies": [
    "string"
  ],
  "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "190e5d1d-7016-4efe-9988-3ebfecb21192",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "status": "Active",
  "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 Account Updated webhook

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

Request body

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

Payload

Element	Description
`AccountId`	Required Unique identifier for the account held with ClearBank. Type: `string` Format: `GUID`
`Name`	Required Name of the account. Type: `string` Min. Length: `1` Max. Length: `500`
`Label`	Required Friendly label for the account. Type: `string` Min. Length: `1` Max. Length: `100`
`Owner`	Required The name used to identify the legal owner of the account. Type: `string` Min. Length: `1` Max. Length: `140`
`Kind`	Required The type of funds the account will hold. Type: `string` Examples: `YourFunds`, `GeneralSegregated`, `DesignatedSegregated`, `GeneralClient`, `DesignatedClient`
`Currencies`	Required Currencies supported by the account. It is an array of strings with each currency represented by a three-letter ISO currency code. Type: `array` Pattern: `^[A-Z]{3}$`
`Status`	Required Current status of the account. Type: `string` Examples: `Active`, `Suspended`, `Closed`
`ProductId`	Optional The product identifier used to determine the behaviour of the account. Only applicable for FSCS accounts. Type: `string` Format: `GUID`
`CustomerId`	Optional Unique identifier for the customer that the account is associated with. Only applicable for FSCS accounts. Type: `string` Format: `GUID`
`Identifiers`	Required List of identifiers. It is an array of objects with an Identifier and Kind. Type: `array` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `50` `Kind` The kind of account identifier provided to uniquely identify the account. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time the account was created. Time in UTC. Type: `string` Format: `date-time`
`TimestampModified`	Required Date and time the account was last modified. Time in UTC. Type: `string` Format: `date-time`
`StatusReason`	Optional Reason for changing the current status of the 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`
`Type`	Required The type of account. Valid options include: Customer, Operating, MinimumMandatedBalance, Treasury, HeldSuspense, RepairSuspense, Institution. Type: `string`

Example account updated webhook request body

{
    "InstitutionId":"18be20af-77a9-4b10-b34d-759854c4f5df",
    "Type":"Accounts.AccountUpdated",
    "Version":1,
    "Payload":{
        "AccountId":"1afe639b-60d0-4d88-8b81-046dcf0219f7",
        "Name":"Gen Seg Eco Bank",
        "Label":"Mid tier asset funds",
        "Owner":"Eco Bank",
        "Kind":"YourFunds",
        "Currencies":[
            "EUR"
        ],
        "Status":"Suspended",
        "ProductId":"8026e2f2-d127-422d-ae10-ef689282b11d",
        "CustomerId":"ba13205e-0ad3-406c-963b-14561d583bf3",
        "Identifiers":[
            {
                "Identifier":"GB29CLRB40391731926000",
                "Kind":"Iban"
            }
        ],
        "TimestampCreated":"2020-10-22T20:50:17.7107385",
        "TimestampModified":"2021-05-09T07:26:12.2224526",
        "StatusReason":"FraudThirdParty",
        "StatusInformation":"Customer spotted some unrecognised transactions on their account",
        "Type":"Customer"
    },
    "Nonce":732392098
}

Example webhook response

{
    "Nonce": 732392098
}

Update the status of an account (real)

patch/mccy/v1/Accounts/{accountId}/status

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

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /mccy/v1/Accounts.
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 account.
Enum array
Active, Suspended
statusReason string
Reason to support the desired status of the 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": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "name": "Gen Seg Eco Bank",
  "label": "Mid tier asset funds",
  "owner": "Eco Bank",
  "kind": "GeneralSegregated",
  "currencies": [
    "string"
  ],
  "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "190e5d1d-7016-4efe-9988-3ebfecb21192",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "status": "Active",
  "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 Account Updated webhook

Get the balance of an account (real)

get/mccy/v1/Accounts/{accountId}/balances

This endpoint is used to retrieve the balance of an account.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /mccy/v1/Accounts.
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)

200 OK
400 Bad Request
404 Not Found

OK

{
  "balances": {
    "EUR": {
      "Available": 100,
      "Actual": 120
    },
    "USD": {
      "Available": 550.5,
      "Actual": 750.5
    },
    "CZK": {
      "Available": 0,
      "Actual": 0
    }
  }
}

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

Close an existing account (real)

delete/mccy/v1/Accounts/{accountId}

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

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /mccy/v1/Accounts.
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 Account Updated webhook