Account reporting

Multi-currency transaction endpoints allow you to retrieve:

A list of transactions for a multi-currency account and any virtual accounts associated with it
A list of transactions for a virtual multi-currency account
A single transaction

You can also access Multi-currency statements.

Get full transaction list for an account

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

This endpoint is used to retrieve a list of transactions for a real account and any virtual accounts associated with the real account.

Parameters

Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /mccy/v1/Accounts.
PageNumber integer, query
The page number to control returned results into manageable sets. There is a limit of 1000 per request. A request with over 1000 will result in a bad request. Default if not supplied: 1.
PageSize integer, query
The page size to control returned results into manageable sets. There is a limit of 1000 per request. A request with over 1000 will result in a bad request. Default if not supplied: 50.
StartDateTime string, query
When supplied, filters the result set to include the start date and time of when the returned transactions were created. If not supplied, then it defaults to 24 hours ago. If StartDateTime and EndDateTime time are not supplied, all transactions that have occurred in the last 24 hours will be returned.
EndDateTime string, query
When supplied, filters the result set to include the end date and time of the when the returned transactions were created. If not supplied, then it defaults to the current time. If StartDateTime and EndDateTime time are not supplied, all transactions that have occurred in the last 24 hours will be returned.
Currency string, query, Required
The ISO currency code for the currency of the transactions to be returned. For example, EUR.

Response (application/json)

200 OK
400 Bad Request
404 Not Found

OK

{
  "transactions": [
    {
      "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",
      "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
      "virtualAccountId": "0ab10eda-9694-4e02-94d8-77283c7b56c1",
      "endToEndId": "string",
      "reference": "string",
      "ultimateBeneficiary": {
        "accountIdentifiers": [
          {
            "identifier": "string",
            "kind": "string"
          }
        ],
        "payeeName": "string"
      },
      "ultimateRemitter": {
        "accountIdentifiers": [
          {
            "identifier": "string",
            "kind": "string"
          }
        ],
        "payerName": "string"
      },
      "amount": 0,
      "currency": "str",
      "currencyExchange": {
        "rate": 0,
        "margin": 0,
        "currency": "string",
        "amount": 0
      },
      "actualPaymentMethod": "string",
      "requestedPaymentMethod": "string",
      "kind": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "identifiers": [
        {
          "scope": "string",
          "name": "string",
          "identifier": "string"
        }
      ],
      "additionalProperties": [
        {
          "key": "string",
          "value": "string"
        }
      ],
      "settledAt": "2019-08-24T14:15:22Z",
      "valueAt": "2019-08-24T14:15:22Z",
      "cancelledAt": "2019-08-24T14:15:22Z",
      "cancellationCode": "string",
      "reason": "string",
      "status": "string"
    }
  ]
}

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

Get transaction list for a virtual account

get/mccy/v1/VirtualAccounts/{virtualAccountId}/transactions

This endpoint is used to retrieve a list of transactions for a virtual account.

Parameters

virtualAccountId string, path, Required
The unique identifier for the virtual account.
PageNumber integer, query
The page number to control returned results into manageable sets. There is a limit of 1000 per request. A request with over 1000 will result in a bad request. Default if not supplied: 1.
PageSize integer, query
The page size to control returned results into manageable sets. There is a limit of 1000 per request. A request with over 1000 will result in a bad request. Default if not supplied: 50.
StartDateTime string, query
When supplied, filters the result set to include the start date and time of when the returned transactions were created. If not supplied, then it defaults to 24 hours ago. If StartDateTime and EndDateTime time are not supplied, all transactions that have occurred in the last 24 hours will be returned.
EndDateTime string, query
When supplied, filters the result set to include the end date and time of the when the returned transactions were created. If not supplied, then it defaults to the current time. If StartDateTime and EndDateTime time are not supplied, all transactions that have occurred in the last 24 hours will be returned.
Currency string, query, Required
The ISO currency code for the currency of the transactions to be returned. For example, EUR.
Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.

Response (application/json)

200 OK
400 Bad Request
404 Not Found

OK

{
  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "virtualAccountId": "0ab10eda-9694-4e02-94d8-77283c7b56c1",
  "endToEndId": "string",
  "reference": "string",
  "ultimateBeneficiary": {
    "accountIdentifiers": [
      {
        "identifier": "string",
        "kind": "string"
      }
    ],
    "payeeName": "string"
  },
  "ultimateRemitter": {
    "accountIdentifiers": [
      {
        "identifier": "string",
        "kind": "string"
      }
    ],
    "payerName": "string"
  },
  "amount": 0,
  "currency": "str",
  "currencyExchange": {
    "rate": 0,
    "margin": 0,
    "currency": "string",
    "amount": 0
  },
  "actualPaymentMethod": "string",
  "requestedPaymentMethod": "string",
  "kind": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "identifiers": [
    {
      "scope": "string",
      "name": "string",
      "identifier": "string"
    }
  ],
  "additionalProperties": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "settledAt": "2019-08-24T14:15:22Z",
  "valueAt": "2019-08-24T14:15:22Z",
  "cancelledAt": "2019-08-24T14:15:22Z",
  "cancellationCode": "string",
  "reason": "string",
  "status": "string"
}

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

Get a transaction

get/mccy/v1/Transactions/{transactionId}

This endpoint is used to retrieve a transaction.

Parameters

transactionId string, path, Required
The unique identifier for the transaction.
Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.

Response (application/json)

200 OK
400 Bad Request
404 Not Found

OK

{
  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "virtualAccountId": "0ab10eda-9694-4e02-94d8-77283c7b56c1",
  "endToEndId": "string",
  "reference": "string",
  "ultimateBeneficiary": {
    "accountIdentifiers": [
      {
        "identifier": "string",
        "kind": "string"
      }
    ],
    "payeeName": "string"
  },
  "ultimateRemitter": {
    "accountIdentifiers": [
      {
        "identifier": "string",
        "kind": "string"
      }
    ],
    "payerName": "string"
  },
  "amount": 0,
  "currency": "str",
  "currencyExchange": {
    "rate": 0,
    "margin": 0,
    "currency": "string",
    "amount": 0
  },
  "actualPaymentMethod": "string",
  "requestedPaymentMethod": "string",
  "kind": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "identifiers": [
    {
      "scope": "string",
      "name": "string",
      "identifier": "string"
    }
  ],
  "additionalProperties": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "settledAt": "2019-08-24T14:15:22Z",
  "valueAt": "2019-08-24T14:15:22Z",
  "cancelledAt": "2019-08-24T14:15:22Z",
  "cancellationCode": "string",
  "reason": "string",
  "status": "string"
}

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

Your multi-currency bank statement is an official summary of financial transactions that have occurred for all multi-currency accounts within a calendar month.

Statements can be generated either for all accounts associated with your institution, or for a specified real account associated with your institution. The statement will be provided via a webhook (see Use webhooks).

Request a statement for all accounts

post/mccy/v1/StatementRequests

This endpoint is used to request a statement for all accounts associated with your institution (as per the specified currency).

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.

Request Payload (application/json)

year integer, Required
Year for which to generate the statement, specified using the Four Digit Year format (e.g., 2021). Cannot be for more than 24 months in the past.
Minimum
2019
month integer, Required
Month for which to generate the statement, specified using the 1–12 format (e.g., 1 for January and 12 for December). Statement for the previous month can only be generated on or after the 5th day of the current month.
Minimum
1
Maximum
12
format string, Required
Format in which to generate the statement. Valid option includes csv only.
Minimum length
3
Maximum length
3
Pattern
csv
currency string, Required
Three-letter ISO currency code for the currency of the account(s).
Minimum length
3
Maximum length
3

request

{
  "year": 2019,
  "month": 1,
  "format": "str",
  "currency": "str"
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
404 Not Found
422 Client Error

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

Client Error

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

Code copied

Associated Webhooks

Multi-currency Institution Statement webhook

This webhook allows you to download a statement for all accounts associated with your institution.

Request body

{
    "Type":"MCCY.Statements.InstitutionStatement",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`Uri`	Required URI for downloading a statement for all accounts associated with your institution. Type: `string` Min. Length: `1` Format: `URI`
`ValidUntilDate`	Required Date and time the URI will remain valid until. Time in UTC. Type: `string` Min. Length: `1` Format: `date-time`
`Year`	Required Year for which the statement has been generated in the Four Digit Year format (e.g., 2021). Type: `integer` Format: `int32`
`Month`	Required Month for which the statement has been generated in the 1 - 12 format (e.g., 1 for January and 12 for December). Type: `integer` minimum: `1` maximum: `12` Format: `int32`
`Currency`	Required Three-letter ISO currency code for the currency of the accounts for which the statement has been generated. Type: `string` Min. Length: `3` Max. Length: `3`
`Format`	Required File format in which the statement has been generated. Type: `string` Min. Length: `3` Max. Length: `3`

Example institution statement webhook request body

{
    "Uri":"https://s9rzi0fsit.blob.core.windows.net/qhd30vev6g/Statement_EUR_2021_06_01aa9bf5-d56f-485f-bc37-c0c631977216.csv?skoid=9f02b375-e412-410d-bfdc-b7894320c935&sktid=0b131c91-9cfd-4603-a85a-920276f59a0f&skt=2021-07-09T08%3A11%3A33Z&ske=2021-07-10T08%3A11%3A33Z&sks=b&skv=2020-04-08&sv=2020-04-08&st=2021-07-09T07%3A11%3A33Z&se=2021-07-10T08%3A11%3A33Z&sr=b&sp=r&sig=spjcgi9e1o",
    "ValidUntilDate":"2021-07-10T00:00:00Z",
    "Year":2021,
    "Month":6,
    "Currency":"EUR",
    "Format":"csv"
},
{
    "Nonce":795391298
}

Example webhook response

{
    "Nonce": 795391298
}

Request a statement for an account

post/mccy/v1/StatementRequests/account/{iban}

This endpoint is used to request a statement for a specific account associated with your institution (as per the specified currency), excluding virtual accounts.

Parameters

iban string, path, Required
The unique International Bank Account number.
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.

Request Payload (application/json)

year integer, Required
Year for which to generate the statement, specified using the Four Digit Year format (e.g., 2021). Cannot be for more than 24 months in the past.
Minimum
2019
month integer, Required
Month for which to generate the statement, specified using the 1–12 format (e.g., 1 for January and 12 for December). Statement for the previous month can only be generated on or after the 5th day of the current month.
Minimum
1
Maximum
12
format string, Required
Format in which to generate the statement. Valid option includes csv only.
Minimum length
3
Maximum length
3
Pattern
csv
currency string, Required
Three-letter ISO currency code for the currency of the account(s).
Minimum length
3
Maximum length
3

request

{
  "year": 2019,
  "month": 1,
  "format": "str",
  "currency": "str"
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
404 Not Found
422 Client Error

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

Client Error

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

Code copied

Associated Webhooks

Multi-currency Account Statement webhook

This webhook allows you to download a statement for a specific multi-currency account associated with your institution.

Request body

{
    "Type":"MCCY.Statements.AccountStatement",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`Uri`	Required URI for downloading a statement for a specific account associated with your institution. Type: `string` Min. Length: `1` Format: `URI`
`ValidUntilDate`	Required Date and time the URI will remain valid until. Time in UTC. Type: `string` Min. Length: `1` Format: `date-time`
`Year`	Required Year for which the statement has been generated in the Four Digit Year format (e.g., 2021). Type: `integer` Format: `int32`
`Month`	Required Month for which the statement has been generated in the 1 - 12 format (e.g., 1 for January and 12 for December). Type: `integer` minimum: `1` maximum: `12` Format: `int32`
`Currency`	Required Three-letter ISO currency code for the currency of the account for which the statement has been generated. Type: `string` Min. Length: `3` Max. Length: `3`
`Format`	Required File format in which the statement has been generated. Type: `string` Min. Length: `3` Max. Length: `3`
`AccountIban`	Required International Bank Account Number for the account for which the statement has been generated. Type: `string` Min. Length: `1` Max. Length: `50`

Example account statement webhook request body

{
    "Uri":"https://s4u4h7sizl.blob.core.windows.net/dyx5atvaaz/Statement_EUR_2021_6_GB88BARC20035395232336_16a67e34-dc12-4fe4-a8e0-4c439a8cbd5e.csv?skoid=9330a684-1fc0-4b94-a2de-8c964bb798ef&sktid=f630ca29-77a1-43ec-9b3a-4e413c4fc4dfe&skt=2021-07-09T06%3A40%3A54Z&ske=2021-07-10T06%3A40%3A54Z&sks=b&skv=2020-04-08&sv=2020-04-08&st=2021-07-09T05%3A40%3A54Z&se=2021-07-10T06%3A40%3A53Z&sr=b&sp=r&sig=m0kdbayo1e",
    "ValidUntilDate":"2021-07-10T00:00:00Z",
    "Year":2021,
    "Month":6,
    "Currency":"EUR",
    "Format":"csv",
    "AccountIban":"GB88BARC20035395232336"
},
{
    "Nonce":748391298
}

Example webhook response

{
    "Nonce": 748391298
}

Account reporting

Multi-currency transactions

Get full transaction list for an account

Parameters

Response (application/json)

Get transaction list for a virtual account

Parameters

Response (application/json)

Get a transaction

Parameters

Response (application/json)

Multi-currency statements

Request a statement for all accounts

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Request a statement for an account

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks