ClearBank

Multicurrency Accounts

Real Accounts

A multicurrency account is a real account held with ClearBank and can be used to send and/or receive payments. The balance of a multicurrency account is also held by ClearBank.

You can use a multicurrency account to hold multiple non-GBP currency balances under the same IBAN, which can be specified at the time of creating the account via our API. Prior to assigning your desired IBAN to the account, we will validate it to ensure that the IBAN format is acceptable and not already in use.

At this time, you cannot open or hold GBP balances in a multicurrency account. GBP payments to and from a multicurrency account are not currently allowed either and would be rejected as well as returned automatically.

If you already hold a GBP account with ClearBank, your new multicurrency account will be opened under a sort code that is different to the one associated with your existing GBP account. ClearBank will set up the non-GBP currency sort code for you as part of onboarding.

For more information about currencies supported by ClearBank Multicurrency accounts, please speak to your Relationship Manager.

Create a new account

post/mccy/v1/Accounts

This endpoint is used to create a new account.

Parameters

  • 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)

  • 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
  • kind string, Required

    The type of funds the account will hold. Valid options include: 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.

  • routingCode object, Required

    Payment routing information used by ClearBank to associate your bank account with your institution.

  • 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": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "routingCode": {
    "code": "010203",
    "kind": "GBSortCode"
  },
  "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "725a5f09-595a-4db1-946a-8330d423da34"
}
Code copied

Response (application/json)

  • 201 Success
  • 400 Bad Request
  • 403 Forbidden
  • 422 Client Error
  • 500 Server Error

Success

{
  "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": "Other",
  "statusInformation": "Received documentation"
}
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

Get all accounts

get/mccy/v1/Accounts

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

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.

Response (application/json)

  • 200 Success
  • 400 Bad Request
  • 500 Server Error
  • 503 Server Error

Success

{
  "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": "string",
          "kind": "string"
        }
      ],
      "status": "Active",
      "statusReason": "Other",
      "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

Get information for an account

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.

Response (application/json)

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

Success

{
  "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": "Other",
  "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

Not Found

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

Amend the properties of an existing account

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.

  • 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)

  • 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 Success
  • 400 Bad Request
  • 404 Not Found
  • 500 Server Error

Success

{
  "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": "Other",
  "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

Update the status of an existing account

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.

  • 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, Required

    Desired status of the account. Valid options include: Active, Suspended.

  • statusReason string

    Reason to support the desired status of the account. Valid options include: AccountHolderBankrupt, DissatisfiedCustomer, FinancialCrime, FraudFirstParty, FraudThirdParty, 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 Success
  • 400 Bad Request
  • 404 Not Found
  • 500 Server Error

Success

{
  "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": "Other",
  "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

Close an existing account

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.

  • X-Request-Id string, header, Required

    A unique identifier for the request.

Response (application/json)

  • 204 Success
  • 404 Not Found
  • 422 Client Error
  • 500 Server 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

Enable an existing account to support a new currency

post/mccy/v1/Accounts/{accountId}/currencies

This endpoint is used to enable an existing account to support a new currency.

Parameters

  • accountId string, path, Required

    The unique identifier for the account. This can be retrieved from GET/mccy/v1/Accounts.

  • 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)

  • currency string, Required

    The three-letter ISO currency code for the new currency to be supported by the account.

    Minimum length
    3
    Maximum length
    3

request

{
  "currency": "EUR"
}
Code copied

Response (application/json)

  • 200 Success
  • 400 Bad Request
  • 404 Not Found
  • 500 Server Error

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

Retrieve the balance of an account

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.

Response (application/json)

  • 200 Success
  • 400 Bad Request
  • 404 Not Found
  • 500 Server Error

Success

{
  "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

Virtual Accounts

Multicurrency virtual accounts are publicly addressable accounts with their own IBAN. Also known as shadow accounts, multicurrency virtual accounts are linked to real accounts and are used to separate out funds held in real accounts for the purposes of improved reconciliation and liquidity management. Additionally, the responsibility of managing and reconciling virtual accounts rests with you, giving you complete control of such accounts.

Multicurrency virtual accounts are only compatible with General Client Accounts and General Segregated Accounts, and can be created, suspended or activated and closed via the ClearBank API.

Multicurrency virtual accounts are enabled for balances of the same currencies as their associated real accounts. For example, if a real multicurrency account is enabled for CHF, EUR and USD, all virtual accounts opened under that real account are also automatically enabled for the same currencies.

To comply with the Funds Transfer Regulation, it is important that the naming of virtual accounts reflects the legal name of the customer.

Create a new virtual account

post/mccy/v1/VirtualAccounts

This endpoint is used to create a new virtual account.

Parameters

  • 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)

  • accountId string, Required

    Unique identifier for the real account associated with the virtual account.

  • virtualAccount object, Required

    Set of elements used to identify a virtual account.

request

{
  "accountId": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "virtualAccount": {
    "owner": "James Smith",
    "identifiers": [
      {
        "identifier": "GB29CLRB40391731926000",
        "kind": "Iban"
      }
    ]
  }
}
Code copied

Response (application/json)

  • 201 Success
  • 400 Bad Request
  • 404 Not Found
  • 500 Server Error

Success

{
  "id": "3fb8a2ce-064a-4de6-8e92-def9fce8772c",
  "accountId": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "owner": "James Smith",
  "status": "Active",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "statusReason": "Other",
  "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

Server Error

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

Associated Webhooks

Get information for a virtual account

get/mccy/v1/VirtualAccounts/{virtualAccountId}

This endpoint is used to retrieve details related to a virtual account.

Parameters

  • virtualAccountId string, path, Required

    The unique identifier for the virtual account.

Response (application/json)

  • 200 Success
  • 400 Bad Request
  • 404 Not Found
  • 500 Server Error

Success

{
  "id": "3fb8a2ce-064a-4de6-8e92-def9fce8772c",
  "accountId": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "owner": "James Smith",
  "status": "Active",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "statusReason": "Other",
  "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

Server Error

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

Amend the properties of an existing virtual account

patch/mccy/v1/VirtualAccounts/{virtualAccountId}

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

Parameters

  • virtualAccountId string, path, Required

    The unique identifier for the virtual account.

  • 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)

  • owner string, Required

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

    Minimum length
    1
    Maximum length
    140

request

{
  "owner": "James Smith-Jones"
}
Code copied

Response (application/json)

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

Success

{
  "id": "3fb8a2ce-064a-4de6-8e92-def9fce8772c",
  "accountId": "98efba88-c43e-41c5-9d47-0938f2fe7192",
  "owner": "James Smith",
  "status": "Active",
  "identifiers": [
    {
      "identifier": "GB29CLRB40391731926000",
      "kind": "Iban"
    }
  ],
  "statusReason": "Other",
  "statusInformation": "Received documentation"
}
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

Not Found

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

Associated Webhooks

Update the status of an existing virtual account

patch/mccy/v1/VirtualAccounts/{virtualAccountId}/status

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

Parameters

  • virtualAccountId string, path, Required

    The unique identifier for the virtual account.

  • 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, Required

    Desired status of the virtual account. Valid options include: Active, Suspended.

  • statusReason string

    Reason to support the desired status of the virtual account. Valid options include: AccountHolderBankrupt, DissatisfiedCustomer, FinancialCrime, FraudFirstParty, FraudThirdParty, 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 Success
  • 400 Bad Request
  • 404 Not Found
  • 500 Server Error

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

Server Error

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

Associated Webhooks

Close an existing virtual account

delete/mccy/v1/VirtualAccounts/{virtualAccountId}

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

Parameters

  • virtualAccountId string, path, Required

    The unique identifier for the virtual account.

  • accountCloseReason string, query

    Reason for why the account is being closed. Available options include: Other, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DuplicateAccount.

  • X-Request-Id string, header, Required

    A unique identifier for the request.

Response (application/json)

  • 204 Success
  • 404 Not Found
  • 422 Client Error
  • 500 Server 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

Server Error

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

Associated Webhooks