A multi-currency account is a real account held with ClearBank and can be used to send and/or receive payments. The balance of a multi-currency 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.

You can use a multi-currency 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 multi-currency account. GBP payments to and from a multi-currency account are not currently allowed either and would be rejected and returned automatically.

If you already hold a GBP account with ClearBank, your new multi-currency 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 multi-currency accounts, please speak to your Relationship Manager.

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

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
500 Server Error
503 Server 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": "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

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

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

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

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, DissatisfiedCustomer, FinancialCrime, FraudFirstParty, FraudThirdParty, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DuplicateAccount, 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.
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

Multi-currency Account Updated webhook

Add a currency to an existing account (real)

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

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

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.

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

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

Multi-currency Account Updated webhook

Multi-currency virtual accounts are publicly addressable accounts with their own IBAN. Also known as shadow accounts, multi-currency 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.

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

Multi-currency virtual accounts are enabled for balances of the same currencies as their associated real accounts. For example, if a real multi-currency 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 an account (virtual)

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
422 Client Error
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

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

Multi-currency Virtual Account Created webhook

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

Request body

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

Payload

Element	Description
`VirtualAccountId`	Required Account identifier used to uniquely identify the virtual account. Type: `string` Min. Length: `1` Format: `GUID`
`AccountId`	Required Unique identifier for the real account associated with the virtual account. Type: `string` Min. Length: `1` Format: `GUID`
`BatchId`	Required Unique batch identifier specified while creating a batch of virtual accounts. Type: `string` Min. Length: `1` Format: `GUID`
`Owner`	Required The name used to identify the legal owner of the virtual account. Type: `string` Min. Length: `1` Max. Length: `140`
`Status`	Required The current status of the virtual account. Type: `string` Examples: `Active`, `Suspended`, `Closed`
`Identifiers`	Required List of identifiers. It is an array of objects with an Identifier and Kind. Type: `array` `Identifier` Unique virtual account identifier value that corresponds to the specified virtual account identifier kind. Type: `string` Min. Length: `1` Max. Length: `50` `Kind` The kind of virtual account identifier provided to uniquely identify the virtual account. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time the virtual account was created. Time in UTC. Type: `string` Format: `date-time`

Example virtual account created webhook request body

{
    "Type":"Accounts.VirtualAccountCreated",
    "Version":1,
    "InstitutionId":"4befdd75-5297-44b3-b70f-234d8a525dd2",
    "Payload":{
        "VirtualAccountId":"b3c93a68-5992-4f83-99d5-f13405fd2d90",
        "AccountId":"d55149f7-f052-49cc-865b-7446b4fb05f5",
        "BatchId":"21d70e60-61f0-4bfb-bd22-a460216947b4",
        "Owner":"Joe Brown",
        "Status":"Active",
        "Identifiers":[
            {
                "Identifier":"GB88BARC20040425385198",
                "Kind":"IBAN"
            }
        ],
        "TimestampCreated":"2021-04-08T12:00:00.0000000"
    },
    "Nonce":748364091
}

Example webhook response

{
    "Nonce": 748364091
}

Get information for an account (virtual)

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 account (virtual)

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

Multi-currency Virtual Account Updated webhook

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

Request body

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

Payload

Element	Description
`VirtualAccountId`	Required Account identifier used to uniquely identify the virtual account. Type: `string` Min. Length: `1` Format: `GUID`
`AccountId`	Required Unique identifier for the real account associated with the virtual account. Type: `string` Min. Length: `1` Format: `GUID`
`Owner`	Required The name used to identify the legal owner of the virtual account. Type: `string` Min. Length: `1` Max. Length: `140`
`Status`	Required The current status of the virtual account. Type: `string` Examples: `Active`, `Suspended`, `Closed`
`Identifiers`	Required List of identifiers. It is an array of objects with an Identifier and Kind. Type: `array` `Identifier` Unique virtual account identifier value that corresponds to the specified virtual account identifier kind. Type: `string` Min. Length: `1` Max. Length: `50` `Kind` The kind of virtual account identifier provided to uniquely identify the virtual account. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time the virtual account was created. Time in UTC. Type: `string` Format: `date-time`
`TimestampModified`	Required Date and time the virtual account was last modified. Time in UTC. Type: `string` Format: `date-time`
`StatusReason`	Optional Reason for changing the current status of the virtual account. Valid options include: AccountHolderBankrupt, DissatisfiedCustomer, FinancialCrime, FraudFirstParty, FraudThirdParty, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DuplicateAccount, Other. Type: `string`
`StatusInformation`	Optional Additional information to support the specified status reason. Type: `string` Min. Length: `0` Max. Length: `100`

Example virtual account updated webhook request body

{
    "Type":"Accounts.VirtualAccountUpdated",
    "Version":1,
    "Payload":{
        "VirtualAccountId":"2a77e175-9bf2-4e0b-a8ca-4cee0610cf26",
        "AccountId":"78b208f0-498e-4412-b462-68beadb6e555",
        "Owner":"E2E Financial Services Limited",
        "Status":"Suspended",
        "Identifiers":[
            {
                "Identifier":"GB43CLRB04040545703930",
                "Kind":"Iban"
            }
        ],
        "TimestampCreated":"2021-07-21T09:06:33.0628794Z",
        "TimestampModified":"2021-07-21T10:00:45.3113241Z",
        "StatusReason":null,
        "StatusInformation":null
    },
    "Nonce":177103143
}

Example webhook response

{
    "Nonce": 177103143
}

Update the status of an account (virtual)

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

Multi-currency Virtual Account Updated webhook

Close an account (virtual)

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

Multi-currency Virtual Account Updated webhook

Manage multi-currency accounts

Real MCCY accounts

Create a new account (real)

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Get all accounts (real)

Parameters

Response (application/json)

Get information for an account (real)

Parameters

Response (application/json)

Amend the properties of an account (real)

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Update the status of an account (real)

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Add a currency to an existing account (real)

Parameters

Request Payload (application/json)

Response (application/json)

Get the balance of an account (real)

Parameters

Response (application/json)

Close an existing account (real)

Parameters

Response (application/json)

Associated Webhooks

Virtual MCCY accounts

Create an account (virtual)

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Get information for an account (virtual)

Parameters

Response (application/json)

Amend the properties of an account (virtual)

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Update the status of an account (virtual)

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Close an account (virtual)

Parameters

Response (application/json)

Associated Webhooks