Czech standard for Open Banking
general notes
Unless explicitly stated otherwise, for all request is expected following definition of processed headers.
- Content-Type:
- Typ: string
- Obligation: yes
- Description: Specification of transfer format. Assuming on technical specification for this API standard is in this case primarily supported format application/json.
- API-key:
- Typ: string
- Obligation: no
- Description: Optional string provided by third party as identifier of request from third party which is iused as configuration element of comunication.
- Authorization:
- Type: string
- Obligation: yes
- Description: Parameter which is used for handover to access token of authenticated user together with its type.
Paths
/accounts
List of clients payment accounts
Paged list of clients accounts. Each account contains unique ID usable for URI reference eg. on account detail.
Paging. Number of records for requested page.
Paging. Requested page. + Default: 0
{
"default": 0
}Comma separated list of fields for sorting sorted by importance
Comma separated list of sorting options (ASC, DESC). the order matches the order of the fields in parameter sort.
The flag identifies if the end user is online and the request was made based on his activity.
Identifies the API's end-user IP address. The TPP should fill this value if the IP address can be detected. The address can be in IPv4 or IPv6 format.
{
"maxLength": 50
}An element used to pass on information about what end-user IP port is using.
{
"maxLength": 40
}The element is used to forward information about the end user operating system used.
{
"maxLength": 100
}Contains information about the end-user web browser. The format should be the same as the standard HTTP parameter User-Agent.
{
"maxLength": 200
}Local time on User's device.
End-user GPS coordinates (if the coordinates can be reliably detected).
Required format: GEO:Latitude;Longitude
Based on [RFC2426] in signed degrees format (DDD.dddd)
{
"maxLength": 100
}It contains a unique identifier of end user equipment, if available. For example, a unique mobile device identifier (IMEI).
Unique identifier for each request specified by TPP. It is recommended to use a UUID format with a length of 36 to 60 characters.
{
"maxLength": 60
}Defines MIME media type of the resource. For example application/json or application/x-www-form-urlencoded (OAuth2 /auth resources) and application/xml in case of bulk payment initiation.
{
"maxLength": 50
}Each request of a transaction contains the date and time at which the message was originated. In timestamp format.
IDs that identify the technical or business process within the call of each API request.
For example, it can be used to identify the process of retrieving a transaction history that is provided as a paged response available through multiple requests.
{
"maxLength": 60
}The name of the original TPP that created the request. Eg. ‘Star corporation, a.s.’.
The identification (licence number) of the original TPP that created the request. Eg. ‘CZ013574-15’.
Successful response
Parameter value is not valid (PARAMETER_INVALID)
- Invalid/missing access token = user is not authorized (UNAUTHORISED) - Invalid/missing certificate = provider is not authorized (UNAUTHORISED)
Attribute description not found
Request for non existing page (PAGE_NOT_FOUND)
/accounts/{id}/transactions
Payer account currency eg. CZK
Paged list of transactions for given clients account. COBS non-compliant API
Clients account system ID
Requested currency for multicurrency account eg. CZK
Date and time for start of requested transaction history
Date and time for end of requested transaction history [given date is included]
Paging. Number of records on single page
Paging. Requested page. + Default: 0
{
"default": 0
}Comma-separated list of sort fields, sorted by its meaning
Comma-separated list of sort variants (ASC, DESC). The order matches the order of the fields in the sort parameter.
The flag identifies if the end user is online and the request was made based on his activity.
Identifies the API's end-user IP address. The TPP should fill this value if the IP address can be detected. The address can be in IPv4 or IPv6 format.
{
"maxLength": 50
}An element used to pass on information about what end-user IP port is using.
{
"maxLength": 40
}The element is used to forward information about the end user operating system used.
{
"maxLength": 100
}Contains information about the end-user web browser. The format should be the same as the standard HTTP parameter User-Agent.
{
"maxLength": 200
}Local time on User's device.
End-user GPS coordinates (if the coordinates can be reliably detected).
Required format: GEO:Latitude;Longitude
Based on [RFC2426] in signed degrees format (DDD.dddd)
{
"maxLength": 100
}It contains a unique identifier of end user equipment, if available. For example, a unique mobile device identifier (IMEI).
Unique identifier for each request specified by TPP. It is recommended to use a UUID format with a length of 36 to 60 characters.
{
"maxLength": 60
}Defines MIME media type of the resource. For example application/json or application/x-www-form-urlencoded (OAuth2 /auth resources) and application/xml in case of bulk payment initiation.
{
"maxLength": 50
}Each request of a transaction contains the date and time at which the message was originated. In timestamp format.
IDs that identify the technical or business process within the call of each API request.
For example, it can be used to identify the process of retrieving a transaction history that is provided as a paged response available through multiple requests.
{
"maxLength": 60
}The name of the original TPP that created the request. Eg. ‘Star corporation, a.s.’.
The identification (licence number) of the original TPP that created the request. Eg. ‘CZ013574-15’.
Succeful response
- Parameter value is invalid (PARAMETER_INVALID) - [InvalidAccountCurrency] - for multicurrency accounts, or unsupported currency by exchange rates (AC09) - [InvalidDate] invalid date (DT01)
- Invalid/missing access token = user is not authorized (UNAUTHORISED) - Invalid/missing certificate = provider is not authorized (UNAUTHORISED)
Attribute description not found
- Invalid or uknown account ID (ID_NOT_FOUND)
- Request for non-existent page (PAGE_NOT_FOUND)
/accounts/{id}/balance
Balance on account
Balance on account for specific clients account ID.
Clients account system ID
Requested currency for multicurrency account. eg. CZK
The flag identifies if the end user is online and the request was made based on his activity.
Identifies the API's end-user IP address. The TPP should fill this value if the IP address can be detected. The address can be in IPv4 or IPv6 format.
{
"maxLength": 50
}An element used to pass on information about what end-user IP port is using.
{
"maxLength": 40
}The element is used to forward information about the end user operating system used.
{
"maxLength": 100
}Contains information about the end-user web browser. The format should be the same as the standard HTTP parameter User-Agent.
{
"maxLength": 200
}Local time on User's device.
End-user GPS coordinates (if the coordinates can be reliably detected).
Required format: GEO:Latitude;Longitude
Based on [RFC2426] in signed degrees format (DDD.dddd)
{
"maxLength": 100
}It contains a unique identifier of end user equipment, if available. For example, a unique mobile device identifier (IMEI).
Unique identifier for each request specified by TPP. It is recommended to use a UUID format with a length of 36 to 60 characters.
{
"maxLength": 60
}Defines MIME media type of the resource. For example application/json or application/x-www-form-urlencoded (OAuth2 /auth resources) and application/xml in case of bulk payment initiation.
{
"maxLength": 50
}Each request of a transaction contains the date and time at which the message was originated. In timestamp format.
IDs that identify the technical or business process within the call of each API request.
For example, it can be used to identify the process of retrieving a transaction history that is provided as a paged response available through multiple requests.
{
"maxLength": 60
}The name of the original TPP that created the request. Eg. ‘Star corporation, a.s.’.
The identification (licence number) of the original TPP that created the request. Eg. ‘CZ013574-15’.
Successful response
[InvalidAccountCurrency] - for multicurrency accounts, or unsupported currency by list of currencies (AC09)
- Invalid/missing access token = user is not authorized (UNAUTHORISED) - Invalid/missing certificate = provider is not authorized (UNAUTHORISED)
Attribute description not found
Invalid or unknown account ID (ID_NOT_FOUND)
/standingorders
List of client’s standing orders
Paged list of client’s standing orders. Each standing order contains a unique id usable for URI referencing, e.g. for the standing order detail.
Resource characteristics:
- Authorization: request requires the authorization of user/client as part of API calling
- Use certificate: request requires the use of the qualified third-party certificate
- Paging: yes
- Sorting: yes
- Filtering: yes
Date and time of the start of required transaction history.
Date and time of the end of required transaction history [inclusive].
Required account currency for multi-currency accounts.
{
"pattern": "[A-Z]{3}"
}Stránkování. Počet záznamů na stránce stránky
Stránkování. Požadovaná stránka. + Default: 0
{
"default": 0
}Čárkou oddělený seznam polí pro třídění seřazený podle významu
Čárkou oddělený seznam způsobů řazení (ASC, DESC). Pořadí odpovídá pořadí polí v parametru sort.
Defines MIME media type of the resource. For example application/json or application/x-www-form-urlencoded (OAuth2 /auth resources) and application/xml in case of bulk payment initiation.
{
"maxLength": 50
}Unique identifier for each request specified by TPP. It is recommended to use a UUID format with a length of 36 to 60 characters.
{
"maxLength": 60
}Each request of a transaction contains the date and time at which the message was originated. In timestamp format.
IDs that identify the technical or business process within the call of each API request.
For example, it can be used to identify the process of retrieving a transaction history that is provided as a paged response available through multiple requests.
{
"maxLength": 60
}The flag identifies if the end user is online and the request was made based on his activity.
Identifies the API's end-user IP address. The TPP should fill this value if the IP address can be detected. The address can be in IPv4 or IPv6 format.
{
"maxLength": 50
}An element used to pass on information about what end-user IP port is using.
{
"maxLength": 40
}The element is used to forward information about the end user operating system used.
{
"maxLength": 100
}Contains information about the end-user web browser. The format should be the same as the standard HTTP parameter User-Agent.
{
"maxLength": 200
}Local time on User's device.
End-user GPS coordinates (if the coordinates can be reliably detected).
Required format: GEO:Latitude;Longitude
Based on [RFC2426] in signed degrees format (DDD.dddd)
{
"maxLength": 100
}It contains a unique identifier of end user equipment, if available. For example, a unique mobile device identifier (IMEI).
The name of the original TPP that created the request. Eg. ‘Star corporation, a.s.’.
The identification (licence number) of the original TPP that created the request. Eg. ‘CZ013574-15’.
application/octet-stream
OK
{
"headers": {
"X-Request-ID": {
"description": "Unique identifier for each request specified by TPP returned in response header.\n",
"type": "string"
}
},
"schema": {
"allOf": [
{
"description": "Stránkovaná kolekce",
"properties": {
"nextPage": {
"description": "Číslo následující stránky. Pokud je aktuální stránka zároveň poslední stránkou seznamu, není tento parametr uveden resp. je uveden s hodnotou null.",
"type": "integer"
},
"pageCount": {
"description": "Celkový počet stránek dotazu",
"type": "integer"
},
"pageNumber": {
"description": "Číslo aktuální stránky",
"type": "integer"
},
"pageSize": {
- Request for a non-existing page (PAGE_NOT_FOUND)
- The value of the parameter is not valid (PARAMETER_INVALID)
{
"headers": {
"X-Request-ID": {
"description": "Unique identifier for each request specified by TPP returned in response header.\n",
"type": "string"
}
},
"schema": {
"properties": {
"errors": {
"description": "Nadřazený element obsahující kolekci všech chybových stavů",
"items": {
"description": "Chybový stav",
"properties": {
"parameters": {
"additionalProperties": true,
"description": "Pole dodatečných elementů specifických pro daný chybový kód. Tyto parametry jsou specifikovány vždy v popis konkrétního chybového kódu.",
"type": "object"
},
"error": {
"description": "Obsahuje specifický chybový kód",
"type": "string"
- Invalid/missing access token = user is not authorized (UNAUTHORISED)
- Invalid/missing certificate = provider is not authorized (UNAUTHORISED)
{
"headers": {
"X-Request-ID": {
"description": "Unique identifier for each request specified by TPP returned in response header.\n",
"type": "string"
}
},
"schema": {
"properties": {
"errors": {
"description": "Nadřazený element obsahující kolekci všech chybových stavů",
"items": {
"description": "Chybový stav",
"properties": {
"parameters": {
"additionalProperties": true,
"description": "Pole dodatečných elementů specifických pro daný chybový kód. Tyto parametry jsou specifikovány vždy v popis konkrétního chybového kódu.",
"type": "object"
},
"error": {
"description": "Obsahuje specifický chybový kód",
"type": "string"
Calling of the method which does not correspond to the licence, or invalid certificate. (FORBIDDEN)
{
"headers": {
"X-Request-ID": {
"description": "Unique identifier for each request specified by TPP returned in response header.\n",
"type": "string"
}
},
"schema": {
"properties": {
"errors": {
"description": "Nadřazený element obsahující kolekci všech chybových stavů",
"items": {
"description": "Chybový stav",
"properties": {
"parameters": {
"additionalProperties": true,
"description": "Pole dodatečných elementů specifických pro daný chybový kód. Tyto parametry jsou specifikovány vždy v popis konkrétního chybového kódu.",
"type": "object"
},
"error": {
"description": "Obsahuje specifický chybový kód",
"type": "string"
/standingorders/{transactionIdentification}
Detail of client’s standing order
Detail of client’s standing order.
Resource characteristics:
- Authorization: request requires the authorization of user/client as part of API calling
- Use certificate: request requires the use of the qualified third-party certificate
- Paging: no
- Sorting: no
- Filtering: no
Transaction identificator
{
"maxLength": 35
}Defines MIME media type of the resource. For example application/json or application/x-www-form-urlencoded (OAuth2 /auth resources) and application/xml in case of bulk payment initiation.
{
"maxLength": 50
}Unique identifier for each request specified by TPP. It is recommended to use a UUID format with a length of 36 to 60 characters.
{
"maxLength": 60
}Each request of a transaction contains the date and time at which the message was originated. In timestamp format.
IDs that identify the technical or business process within the call of each API request.
For example, it can be used to identify the process of retrieving a transaction history that is provided as a paged response available through multiple requests.
{
"maxLength": 60
}The flag identifies if the end user is online and the request was made based on his activity.
Identifies the API's end-user IP address. The TPP should fill this value if the IP address can be detected. The address can be in IPv4 or IPv6 format.
{
"maxLength": 50
}An element used to pass on information about what end-user IP port is using.
{
"maxLength": 40
}The element is used to forward information about the end user operating system used.
{
"maxLength": 100
}Contains information about the end-user web browser. The format should be the same as the standard HTTP parameter User-Agent.
{
"maxLength": 200
}Local time on User's device.
End-user GPS coordinates (if the coordinates can be reliably detected).
Required format: GEO:Latitude;Longitude
Based on [RFC2426] in signed degrees format (DDD.dddd)
{
"maxLength": 100
}It contains a unique identifier of end user equipment, if available. For example, a unique mobile device identifier (IMEI).
The name of the original TPP that created the request. Eg. ‘Star corporation, a.s.’.
The identification (licence number) of the original TPP that created the request. Eg. ‘CZ013574-15’.
application/octet-stream
OK
{
"headers": {
"X-Request-ID": {
"description": "Unique identifier for each request specified by TPP returned in response header.\n",
"type": "string"
}
},
"schema": {
"allOf": [
{
"description": "Standing order identification and amount.\n",
"properties": {
"amount": {
"description": "Payment amount\n",
"properties": {
"instructedAmount": {
"description": "Amount and currency in the instruction\n",
"properties": {
"currency": {
"description": "Defined account currency.\n\nCurrency code according to ISO 4217 = 3 capital letters.\n",
"example": "CZK",
"pattern": "[A-Z]{3}",
- Invalid/missing access token = user is not authorized (UNAUTHORISED)
- Invalid/missing certificate = provider is not authorized (UNAUTHORISED)
{
"headers": {
"X-Request-ID": {
"description": "Unique identifier for each request specified by TPP returned in response header.\n",
"type": "string"
}
},
"schema": {
"properties": {
"errors": {
"description": "Nadřazený element obsahující kolekci všech chybových stavů",
"items": {
"description": "Chybový stav",
"properties": {
"parameters": {
"additionalProperties": true,
"description": "Pole dodatečných elementů specifických pro daný chybový kód. Tyto parametry jsou specifikovány vždy v popis konkrétního chybového kódu.",
"type": "object"
},
"error": {
"description": "Obsahuje specifický chybový kód",
"type": "string"
Calling of the method which does not correspond to the licence, or invalid certificate. (TRANSACTION_MISSING)
{
"headers": {
"X-Request-ID": {
"description": "Unique identifier for each request specified by TPP returned in response header.\n",
"type": "string"
}
},
"schema": {
"properties": {
"errors": {
"description": "Nadřazený element obsahující kolekci všech chybových stavů",
"items": {
"description": "Chybový stav",
"properties": {
"parameters": {
"additionalProperties": true,
"description": "Pole dodatečných elementů specifických pro daný chybový kód. Tyto parametry jsou specifikovány vždy v popis konkrétního chybového kódu.",
"type": "object"
},
"error": {
"description": "Obsahuje specifický chybový kód",
"type": "string"
Method not implemented (NOT_IMPLEMENTED)
{
"headers": {
"X-Request-ID": {
"description": "Unique identifier for each request specified by TPP returned in response header.\n",
"type": "string"
}
},
"schema": {
"properties": {
"errors": {
"description": "Nadřazený element obsahující kolekci všech chybových stavů",
"items": {
"description": "Chybový stav",
"properties": {
"parameters": {
"additionalProperties": true,
"description": "Pole dodatečných elementů specifických pro daný chybový kód. Tyto parametry jsou specifikovány vždy v popis konkrétního chybového kódu.",
"type": "object"
},
"error": {
"description": "Obsahuje specifický chybový kód",
"type": "string"
Definitions
Clients account
{
"type": "object",
"required": [
"id",
"identification",
"servicer"
],
"properties": {
"id": {
"type": "string",
"description": "API identifier of payment account API identifier of payment account"
},
"identification": {
"$ref": "#/definitions/AccountIdentification"
},
"currency": {
"type": "string",
"description": "Payer account currency eg. CZK"
},
"servicer": {
"$ref": "#/definitions/AccountServicer"
},
"nameI18N": {
"type": "string",
"description": "Account name"
},
"productI18N": {
"type": "string",
"description": "Product name"
},
"ownersNames": {
"$ref": "#/definitions/ownersNames"
}
}
}
Payer account identification
{
"type": "object",
"required": [
"iban"
],
"properties": {
"iban": {
"type": "string",
"description": "IBAN"
},
"other": {
"type": "string",
"description": "Other identifier of payer account eg. account number"
}
}
}
Array of name/s of the account holder/s for consumers or trade name/s for commercial clients
{
"type": "array",
"example": [
"Jan Bílý",
"Adam Červené",
"Petr Žlutá"
],
"items": {
"$ref": "#/definitions/ownerName"
}
}
Name and Surname of the owner
{
"type": "string",
"maxLength": 100
}
Collection of clients accounts
{
"allOf": [
{
"$ref": "#/definitions/PagedList"
},
{
"type": "object",
"required": [
"page"
],
"properties": {
"page": {
"type": "array",
"items": {
"$ref": "#/definitions/Account"
}
}
}
}
]
}
{
"type": "object",
"properties": {
"bankCode": {
"type": "string"
},
"countryCode": {
"type": "string",
"description": "Country of the bank"
},
"bic": {
"type": "string",
"description": "BIC code of the bank"
}
}
}
Clients payment account balance
{
"type": "object",
"required": [
"type",
"amount",
"creditDebitIndicator",
"date"
],
"properties": {
"type": {
"$ref": "#/definitions/BalanceType"
},
"creditLine": {
"$ref": "#/definitions/BalanceTypeCreditLine"
},
"amount": {
"$ref": "#/definitions/MonetaryAmount"
},
"creditDebitIndicator": {
"type": "string",
"description": "Indication if balance on requested account is positive or negative"
},
"date": {
"$ref": "#/definitions/DateTimeDateTime"
}
}
}
Collection of account balances on clients payment account
{
"type": "object",
"required": [
"balances"
],
"properties": {
"balances": {
"type": "array",
"items": {
"$ref": "#/definitions/Balance"
}
}
}
}
{
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Balance type codes"
}
}
}
Amount of allowed debit / overdraft
{
"type": "object",
"properties": {
"included": {
"type": "boolean"
},
"amount": {
"$ref": "#/definitions/MonetaryAmountOptional"
}
}
}
Describes balance type, for which belongs information about balance
{
"type": "object",
"required": [
"codeOrProprietary"
],
"properties": {
"codeOrProprietary": {
"$ref": "#/definitions/BalanceTypeCodeOrProprietary"
}
}
}
Date and time by ISO 8601
{
"type": "object",
"required": [
"dateTime"
],
"properties": {
"dateTime": {
"description": "Date or date and time by ISO 8601",
"type": "string",
"format": "date-time"
}
}
}
Monetary amount
{
"type": "object",
"required": [
"value",
"currency"
],
"properties": {
"value": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "Currency eg. CZK"
}
}
}
Monetary amount (optional attributes)
{
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "Currency eg. CZK"
}
}
}
Paged collection
{
"type": "object",
"required": [
"pageNumber",
"pageCount",
"pageSize"
],
"properties": {
"pageNumber": {
"type": "integer",
"description": "Number of current page"
},
"pageCount": {
"type": "integer",
"description": "Total number of query pages"
},
"nextPage": {
"type": "integer",
"description": "Number of the following page. In case if current page is last page of list, this parametr is not listed, respectiveli is listed with value null."
},
"pageSize": {
"type": "integer",
"description": "Number of records on page. This parameter can respond to requested value of size from request except when it is the last page, or in case when requested range of pages exceeded maximal limit defined for specific API source."
},
"totalCount": {
"type": "integer",
"description": "Optional parameter which informs about number of records over all pages. If it´s impossible to exactly define this value it is not filled."
}
}
}
Transaction
{
"type": "object",
"required": [
"bookingDate",
"amount"
],
"properties": {
"bookingDate": {
"description": "Booking date",
"type": "string",
"format": "date"
},
"transactionType": {
"description": "Transaction category",
"type": "string"
},
"counterPartyAccount": {
"description": "Counter part account number",
"$ref": "#/definitions/TransactionAccount"
},
"productBankRef": {
"description": "Product ID, which belongs to transaction (eg. payment card number)",
"type": "string"
},
"amount": {
"description": "Amount",
"$ref": "#/definitions/MonetaryAmount"
},
"fee": {
"description": "Fee",
"$ref": "#/definitions/MonetaryAmount"
},
"description": {
"description": "Description",
"type": "string"
}
}
}
Paged collection
{
"allOf": [
{
"$ref": "#/definitions/PagedList"
},
{
"type": "object",
"required": [
"page"
],
"properties": {
"page": {
"type": "array",
"items": {
"$ref": "#/definitions/Transaction"
}
}
}
}
]
}
Account
{
"type": "object",
"required": [
"accountNumber",
"bankCode"
],
"properties": {
"accountNumberPrefix": {
"description": "Prefix",
"type": "string"
},
"accountNumber": {
"description": "Account number",
"type": "string"
},
"bankCode": {
"description": "Bank code",
"type": "string"
},
"accountName": {
"description": "Account name",
"type": "string"
}
}
}
Error status
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Contains specific error code"
},
"parameters": {
"type": "object",
"additionalProperties": true,
"description": "Field with additiona specific elements for error code. These parameters are every time specified in description of specific error."
},
"scope": {
"type": "string",
"description": "Defines JSON path of request element, which leads to causing of error status."
},
"message": {
"type": "string",
"description": "Optional text description. It´s not used to interpretation for client. It is used for example to enriche error log."
}
}
}
{
"type": "object",
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "Parent element with collection of all error statuses",
"items": {
"$ref": "#/definitions/Error"
}
}
}
}