ClearBank

API

GBP Accounts

GBP Payments

Multi-currency/FX

Embedded Banking

Savings accounts

Savings accounts

ClearBank supports savings accounts. A savings account is an FSCS-protected account that can accrue interest on behalf of a customer. If you'd like access to this product, please speak to your Client Director.

You can choose how much interest to pay customers. ClearBank will calculate accruals and post regular interest payments. For information on how to set up interest configurations, refer to Interest configuration.

To create a savings account:

  1. Check that you already have a customer defined. This can be a retail or business customer. If you need to create a retail customer, use the Create a retail customer endpoint.
  2. Use the POST /v1/savings endpoint to create the account on behalf of the customer.

    The interestConfigurationId field is used to provide the initial interest configuration ID when creating the savings account (refer to Interest configuration).

  3. Set the nominated account using the PUT /v1/accounts/{accountId}/nominated-account endpoint.

    Note: A nominated account is the account that accrued interest, if any, will be transferred into upon closure of the savings account. Name matching between accounts is your responsibility.

Submit the POST /v1/savings endpoint. Once you receive a 201 response, submit the PUT /v1/accounts/{accountId}/nominated-account to set up a nominated account. Once you receive a 200 response, funds can now be added to the savings account.

Once you have opened a savings account, you can deposit and withdraw payments using the Faster Payments or CHAPS payment endpoints. Incoming or outgoing Bacs payments are not accepted.

You can retrieve information on all savings accounts by using the GET /v3/accounts endpoint and filtering for savings accounts, or retrieve information for a specific savings account through the GET /v3/Accounts/{accountId} endpoint.

You can amend a savings account with the PATCH /v1/accounts/{accountId} endpoint.

To retrieve end of day balances for a savings account, use the camt.053 endpoints.

To close a savings account:

  1. Withdraw all funds from the account.
  2. Verify that a nominated account has been defined. You can obtain details of the currently configured nominated account using the GET /v1/accounts/{accountId}/nominated-account endpoint.
  3. Use the POST /v1/accounts/{id}/closure endpoint.

    The process is asynchronous and can take longer if an interest calculation is pending. Unpaid accrued interest, if any, will be deposited into the nominated account. If there is no interest to be paid, then it's possible to close the account without a nominated account being defined.

  4. OPTIONAL Check closure status using the GET /v1/accounts/{id}/closure endpoint.
  5. The Account Closure Completed webhook will be sent once the account has closed.

To close an account, set the nominated account using the PUT /v1/accounts/{accountId}/nominated-account endpoint. Once you receive a 200 response, submit the PUT /v1/accounts/{accountId}/nominated-account to set up a nominated account. Once you receive a 200 response, funds can now be added to the savings account.

Account closure may fail due to the nominated account details being incorrect. You will know from the ClosureFailureReason field in the Account Closure Failed webhook.

See the following possible combinations of accountStatus and closureStatus:

accountStatusclosureStatusDescription
EnabledNoneNo closure request submitted
EnabledPendingClosure requested, interest being calculated
EnabledFailedClosure request failed, see closureFailureReasons field for details
SuspendedPendingClosure requested for suspended account, interest being calculated
ClosedCompleteClosure completed successfully


To reset the nominated account and close the account:

  1. OPTIONAL Obtain details of the currently configured nominated account using the GET /v1/accounts/{accountId}/nominated-account endpoint.
  2. Correct the nominated account details using the PUT /v1/accounts/{accountId}/nominated-account endpoint.
  3. Use the POST /v1/accounts/{id}/closure endpoint.

    The process is asynchronous. Unpaid accrued interest, if any, will be deposited into the nominated account.

  4. OPTIONAL Check closure status using the GET /v1/accounts/{id}/closure endpoint.
  5. The Account Closure Completed webhook will be sent once the account has closed.

To close an account, set the nominated account using the PUT /v1/accounts/{accountId}/nominated-account endpoint. Once you receive a 200 response, submit the PUT /v1/accounts/{accountId}/nominated-account to set up a nominated account. Once you receive a 200 response, funds can now be added to the savings account.

Create a savings account

post/v1/savings

This endpoint is used to create a Savings 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)

  • ownerName string, Required

    The name used to identify the legal owner of the account.

    Minimum length
    1
    Maximum length
    140
    Pattern
    ^[^\|_\[\]<>^`~\\$]*$
  • sortCode string, Required

    The sort code that the account should be created under.

    Pattern
    ^\d{6}$
  • productId string, Required

    The product identifier of the account. It is used to determine the behaviour of the account.

    Pattern
    ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
  • customerId string, Required

    The unique identifier of the customer that holds the account.

    Pattern
    ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
  • interestConfigurationId string

    The unique identifier of the interest configuration. This determines the interest product the account will be using. If you don't have this, speak to your Client Director.

    Pattern
    ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

request

{
  "ownerName": "John Smith",
  "sortCode": "010203",
  "productId": "01234567-89ab-cdef-0123-456789abcdef",
  "customerId": "01234567-89ab-cdef-0123-456789abcdef",
  "interestConfigurationId": "24df1e52-24d9-4bda-86af-c81a7d1932b1"
}
Code copied

Response (application/json)

  • 201 Created
  • 400 Bad Request
  • 404 Not Found
  • 422 Client Error

Created

{
  "account": {
    "accountId": "01234567-89ab-cdef-0123-456789abcdef",
    "productId": "01234567-89ab-cdef-0123-456789abcdef",
    "customerId": "01234567-89ab-cdef-0123-456789abcdef",
    "interestConfigurationId": "24df1e52-24d9-4bda-86af-c81a7d1932b1",
    "accountName": "Savings Account",
    "ownerName": "John Smith",
    "iban": "GB12CLBK01020312345678",
    "bban": "CLBK01020312345678",
    "createdDateTime": "2024-01-01T12:34:56.789+00:00"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}
Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied

Client Error

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied

Associated Webhooks

Set a nominated account

put/v1/accounts/{accountId}/nominated-account

This endpoint is used to set a nominated account.

Parameters

  • accountId string, path, Required

    The unique identifier for the real account associated with the nominated account. This can be retrieved from GET /v3/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)

  • identifier string, Required

    The identifier for the nominated account. IBAN is the preferred format.

    Minimum length
    0
    Maximum length
    50
  • identifierKind string, Required

    The type of identifier for the nominated account. Supported values are 'IBAN', 'BBAN' and 'SCAN' (Sort Code and Account Number).

  • ownerName string, Required

    The name used to identify the legal owner of the nominated account.

    Minimum length
    1
    Maximum length
    140
    Pattern
    ^[0-9a-zA-Z\/\-\?:\(\)\.,’'\+ !#$%&\*=^_`\{\|\}~"";<>@\[\\\]]+$

request

{
  "identifier": "GB29NWBK60161331926819 (IBAN), NWBK60161331926819 (BBAN) or 60161331926819 (SCAN)",
  "identifierKind": "IBAN",
  "ownerName": "John Smith"
}
Code copied

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 404 Not Found

OK

{
  "nominatedAccount": {
    "identifier": "GB12CLBK01020312345678",
    "identifierKind": "IBAN",
    "ownerName": "John Smith"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}
Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied

Get a nominated account

get/v1/accounts/{accountId}/nominated-account

This endpoint is used to get the details of a nominated account.

Parameters

  • accountId string, path, Required

    The unique identifier for the real account associated with the nominated account. This can be retrieved from GET /v3/Accounts.

  • Authorization string, header, Required

    Your API Token, obtained from the ClearBank Portal.

Response (application/json)

  • 200 OK
  • 404 Not Found

OK

{
  "nominatedAccount": {
    "accountId": "01234567-89ab-cdef-0123-456789abcdef",
    "identifier": "GB12CLBK01020312345678",
    "identifierKind": "IBAN",
    "ownerName": "John Smith",
    "createdDateTime": "2024-05-01T00:00:00+01:00",
    "modifiedDateTime": "2024-05-01T00:00:00+01:00"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}
Code copied

Get all real accounts, including savings accounts

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, obtained from the ClearBank Portal.

Response (application/json)

  • 200 OK
  • 400 Bad Request

OK

{
  "accounts": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Sample Account Type Name",
      "label": "John Smith",
      "type": "CACC",
      "currency": "GBP",
      "balances": [
        {
          "name": "Current Account",
          "amount": 0,
          "currency": "GBP",
          "status": "VALU"
        }
      ],
      "minimumBalance": {
        "name": "Current Account",
        "amount": 0,
        "currency": "GBP",
        "status": "VALU"
      },
      "status": "Enabled",
      "statusReason": "AccountHolderDeceased",
      "iban": "GB12CLBK01020312345678",
      "bban": "CLBK01020312345678",
      "upic": "string",
      "cuid": "string"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}
Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied

Get information for a savings account

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, obtained from the ClearBank Portal.

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found

OK

{
  "account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Sample Account Type Name",
    "label": "John Smith",
    "type": "CACC",
    "currency": "GBP",
    "balances": [
      {
        "name": "Current Account",
        "amount": 0,
        "currency": "GBP",
        "status": "VALU"
      }
    ],
    "minimumBalance": {
      "name": "Current Account",
      "amount": 0,
      "currency": "GBP",
      "status": "VALU"
    },
    "status": "Enabled",
    "statusReason": "AccountHolderDeceased",
    "iban": "GB12CLBK01020312345678",
    "bban": "CLBK01020312345678",
    "upic": "string",
    "cuid": "string"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}
Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied

Amend a savings account

patch/v1/accounts/{accountId}

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

Parameters

  • accountId string, path, Required

    The unique identifier for the real 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

    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, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute, Other.

    Enum array
    NotProvided, AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, Other, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute
  • 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": "Enabled",
  "statusReason": "AccountHolderDeceased",
  "ownerName": "John Smith",
  "legalOwnerType": "Personal",
  "relationshipType": "Single",
  "minimumBalance": 0
}
Code copied

Response (application/json)

  • 204 No content
  • 400 Bad Request
  • 403 Forbidden
  • 409 Conflict

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied

Conflict

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied

Close a savings account

post/v1/accounts/{accountId}/closure

This endpoint is used to create an account closure request.

Parameters

  • accountId string, path, Required

    The unique identifier for the 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)

  • closureReason string, Required

    Reason for the account closure request. Valid options include AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute, Other.

    Enum array
    NotProvided, AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, Other, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute

request

{
  "closureReason": "AccountHolderDeceased"
}
Code copied

Response (application/json)

  • 202 Accepted
  • 400 Bad Request
  • 404 Not Found
  • 409 Conflict

Accepted

{
  "accountClosure": {
    "accountId": "01234567-89ab-cdef-0123-456789abcdef",
    "closureReason": "AccountHolderDeceased",
    "closureStatus": "Complete"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}
Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied

Conflict

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied

Associated Webhooks

Get account closure status

get/v1/accounts/{accountId}/closure

Get current status of the account closure request.

Parameters

  • accountId string, path, Required

    The unique identifier for the account.

  • Authorization string, header, Required

    Your API Token, obtained from the ClearBank Portal.

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 404 Not Found

OK

{
  "accountClosure": {
    "accountId": "01234567-89ab-cdef-0123-456789abcdef",
    "accountStatus": "Closed",
    "closureStatus": "Complete",
    "closureFailureReasons": [
      "string"
    ],
    "accountModifiedDateTime": "2024-01-01T12:34:56.789+00:00"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}
Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
Code copied