Our API implements Czech Open Banking standard (COBS) version 3.0 - https://www.czech-ba.cz/cs/aktivity/standardy/cesky-standard-pro-open-banking

Contact

For any question concerning API please contact us via email api@maxbanka.eu.

Not yet implemented

  • consents

Differences from COBS are described in Additional information above specific request.

General information

  • for testing purposes we use test environment,

  • a qualified certificate (QWAC) is required for test and production API access. We recommend qualified certificate from I. Certifikační autorita. Before using certificate you have to verified with us that we have a root certificate that identify your certificate authority (CA).

  • we have to approve TPP registration request (for Test and Production),

  • we will create new users for authorisation testing. We will provide login name and password and you have to provide to us telephone number for authorisation operations,

  • if you need update data for more clients using batch we recommend to use only one thread. If you use more threads the performance of execution can be reduced.

End Points

Example:

https://api-test.expobank.cz/accounts
https://api-test.expobank.cz/accounts/1111110020/balance
https://api-test.expobank.cz/accounts/1111110020/transactions

Example:

https://api.expobank.cz/accounts
https://api.expobank.cz/accounts/1111110020/balance
https://api.expobank.cz/accounts/1111110020/transactions

TPP Registration and auth. API

Register new TPP

A POST request to register new TPP

Additional information

  • for TPP registration request parameter scopes[] is required

Request fields

Path Type Description

application_type

String

Required, web or native. The type of application that will use the client_id. In the case of the web type, the definition of rediect_uris is required in the format of the web uri in the form http/s scheme. For the native type, in redirect_uris it is possible to enter, e.g. the application package, or the own format.

redirect_uris[]

Array

Required, at least 1, max 3 x 2047. Enumeration of URL where the authentication flow is redirected at the end. The authorization request must contain just one of these registered URIs in the exact format.

client_name

String

Required, max 255. Name of the client application

client_name#en-US

String

Max 1024. Name of the client application in the relevant language/coding.

logo_uri

String

Max 2047. URI of the application logo (or the place from where it may be downloaded on the registration)

contact

String

Max 320. E-mail as a contact to the responsible person on the part of the client application.

scopes[]

Array

Zero or more of aisp, pisp, cisp. The field of applications of required scopes. On the registration, scopes are validated against the content of the certificate used.

Response fields

Path Type Description

application_type

String

Required, web or native. The type of application that will use the client_id. In the case of the web type, the definition of rediect_uris is required in the format of the web uri in the form http/s scheme. For the native type, in redirect_uris it is possible to enter, e.g. the application package, or the own format.

redirect_uris[]

Array

Required, at least 1, max 3 x 2047. Enumeration of URL where the authentication flow is redirected at the end. The authorization request must contain just one of these registered URIs in the exact format.

client_name

String

Required, max 255. Name of the client application

client_name#en-US

String

Max 1024. Name of the client application in the relevant language/coding.

logo_uri

String

Max 2047. URI of the application logo (or the place from where it may be downloaded on the registration)

contact

String

Max 320. E-mail as a contact to the responsible person on the part of the client application.

scopes[]

Array

Zero or more of aisp, pisp, cisp. The field of applications of required scopes. On the registration, scopes are validated against the content of the certificate used.

client_id

String

Max 36. The client_id assigned by the application. This ID starts the authentication process and communication is decoded in the replacement of code and refresh_token.

client_secret

String

Max 64. Client secret - password/token issued by the bank IDP for the TPP application (client_id)

client_secret_expires_at

Number

Default value is 0 (client_id never expires). Otherwise, the value is stated in seconds from data 1970-01-01T0:0:0Z

api_key

String

API key

Example

POST /oauth2/register HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Content-Length: 258
Host: localhost:8080

{
  "application_type" : "web",
  "redirect_uris" : [ "https://tpp.cz" ],
  "client_name" : "TEST TPP",
  "client_name#en-US" : "TEST TPP english name",
  "logo_uri" : "https://tpp.cz/logo.png",
  "contact" : "admin@tpp.cz",
  "scopes" : [ "aisp", "pisp" ]
}
HTTP/1.1 201 Created
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 518

{
  "application_type" : "web",
  "redirect_uris" : [ "https://tpp.cz" ],
  "client_name" : "TEST TPP",
  "logo_uri" : "https://tpp.cz/logo.png",
  "contact" : "admin@tpp.cz",
  "scopes" : [ "pisp", "aisp" ],
  "client_id" : "5b20b042-5acf-4a55-b070-928a2ddd153a",
  "client_secret" : "bci65YKoKYZqQvOTdpYiT4wvZFNTqMju18V4gI5YOoFLd3mP70q87K29Q1O8oj6y",
  "client_secret_expires_at" : 0,
  "api_key" : "Km5xHPDIRPV30q4pNlvujaYLU8gZteBrFymE91F7Ffep5oyD8R1Cfu6sbfPV97V5",
  "client_name#en-US" : "TEST TPP english name"
}

TPP registered data

A GET request to get TPP registered info

Path parameters

Table 1. /oauth2/register/{client_id}
Parameter Description

client_id

client_id

Response fields

Path Type Description

application_type

String

Required, web or native. The type of application that will use the client_id. In the case of the web type, the definition of rediect_uris is required in the format of the web uri in the form http/s scheme. For the native type, in redirect_uris it is possible to enter, e.g. the application package, or the own format.

redirect_uris[]

Array

Required, at least 1, max 3 x 2047. Enumeration of URL where the authentication flow is redirected at the end. The authorization request must contain just one of these registered URIs in the exact format.

client_name

String

Required, max 255. Name of the client application

client_name#en-US

String

Max 1024. Name of the client application in the relevant language/coding.

logo_uri

String

Max 2047. URI of the application logo (or the place from where it may be downloaded on the registration)

contact

String

Max 320. E-mail as a contact to the responsible person on the part of the client application.

scopes[]

Array

Zero or more of aisp, pisp, cisp. The field of applications of required scopes. On the registration, scopes are validated against the content of the certificate used.

client_id

String

Max 36. The client_id assigned by the application. This ID starts the authentication process and communication is decoded in the replacement of code and refresh_token.

client_secret

String

Max 64. Client secret - password/token issued by the bank IDP for the TPP application (client_id)

client_secret_expires_at

Number

Default value is 0 (client_id never expires). Otherwise, the value is stated in seconds from data 1970-01-01T0:0:0Z

api_key

String

API key

Example

GET /oauth2/register/5b20b042-5acf-4a55-b070-928a2ddd153a HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 518

{
  "application_type" : "web",
  "redirect_uris" : [ "https://tpp.cz" ],
  "client_name" : "TEST TPP",
  "logo_uri" : "https://tpp.cz/logo.png",
  "contact" : "admin@tpp.cz",
  "scopes" : [ "pisp", "aisp" ],
  "client_id" : "5b20b042-5acf-4a55-b070-928a2ddd153a",
  "client_secret" : "bci65YKoKYZqQvOTdpYiT4wvZFNTqMju18V4gI5YOoFLd3mP70q87K29Q1O8oj6y",
  "client_secret_expires_at" : 0,
  "api_key" : "Km5xHPDIRPV30q4pNlvujaYLU8gZteBrFymE91F7Ffep5oyD8R1Cfu6sbfPV97V5",
  "client_name#en-US" : "TEST TPP english name"
}

Update registered TPP

A PUT request to update registered TPP

To update the information you need to send not only the changed parameters, but also the existing ones.

Path parameters

Table 2. /oauth2/register/{client_id}
Parameter Description

client_id

client_id

Request fields

Path Type Description

application_type

String

Required, web or native. The type of application that will use the client_id. In the case of the web type, the definition of rediect_uris is required in the format of the web uri in the form http/s scheme. For the native type, in redirect_uris it is possible to enter, e.g. the application package, or the own format.

redirect_uris[]

Array

Required, at least 1, max 3 x 2047. Enumeration of URL where the authentication flow is redirected at the end. The authorization request must contain just one of these registered URIs in the exact format.

client_name

String

Required, max 255. Name of the client application

client_name#en-US

String

Max 1024. Name of the client application in the relevant language/coding.

logo_uri

String

Max 2047. URI of the application logo (or the place from where it may be downloaded on the registration)

contact

String

Max 320. E-mail as a contact to the responsible person on the part of the client application.

scopes[]

Array

Zero or more of aisp, pisp, cisp. The field of applications of required scopes. On the registration, scopes are validated against the content of the certificate used.

Response fields

Path Type Description

application_type

String

Required, web or native. The type of application that will use the client_id. In the case of the web type, the definition of rediect_uris is required in the format of the web uri in the form http/s scheme. For the native type, in redirect_uris it is possible to enter, e.g. the application package, or the own format.

redirect_uris[]

Array

Required, at least 1, max 3 x 2047. Enumeration of URL where the authentication flow is redirected at the end. The authorization request must contain just one of these registered URIs in the exact format.

client_name

String

Required, max 255. Name of the client application

client_name#en-US

String

Max 1024. Name of the client application in the relevant language/coding.

logo_uri

String

Max 2047. URI of the application logo (or the place from where it may be downloaded on the registration)

contact

String

Max 320. E-mail as a contact to the responsible person on the part of the client application.

scopes[]

Array

Zero or more of aisp, pisp, cisp. The field of applications of required scopes. On the registration, scopes are validated against the content of the certificate used.

client_id

String

Max 36. The client_id assigned by the application. This ID starts the authentication process and communication is decoded in the replacement of code and refresh_token.

Example

PUT /oauth2/register/5b20b042-5acf-4a55-b070-928a2ddd153a HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Content-Length: 266
Host: localhost:8080

{
  "application_type" : "web",
  "redirect_uris" : [ "https://tpp2.cz" ],
  "client_name" : "TEST TPP 2",
  "client_name#en-US" : "TEST TPP english name 2.",
  "logo_uri" : "https://tpp.cz/logo2.png",
  "contact" : "admin2@tpp.cz",
  "scopes" : [ "aisp", "cisp" ]
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 322

{
  "application_type" : "web",
  "redirect_uris" : [ "https://tpp2.cz" ],
  "client_name" : "TEST TPP 2",
  "logo_uri" : "https://tpp.cz/logo2.png",
  "contact" : "admin2@tpp.cz",
  "scopes" : [ "pisp", "aisp" ],
  "client_id" : "5b20b042-5acf-4a55-b070-928a2ddd153a",
  "client_name#en-US" : "TEST TPP english name 2."
}

Delete registered TPP

A DELETE request to delete registered TPP

Path parameters

Table 3. /oauth2/register/{client_id}
Parameter Description

client_id

client_id

Example

DELETE /oauth2/register/5b20b042-5acf-4a55-b070-928a2ddd153a HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store

Renew Secret

A POST request to renew secret on registered TPP

Path parameters

Table 4. /oauth2/register/{client_id}/renewSecret
Parameter Description

client_id

client_id

Response fields

Path Type Description

client_id

String

Max 36. The client_id assigned by the application. This ID starts the authentication process and communication is decoded in the replacement of code and refresh_token.

client_secret

String

Max 64. Client secret - password/token issued by the bank IDP for the TPP application (client_id)

client_secret_expires_at

Number

Default value is 0 (client_id never expires). Otherwise, the value is stated in seconds from data 1970-01-01T0:0:0Z

Example

POST /oauth2/register/5b20b042-5acf-4a55-b070-928a2ddd153a/renewSecret HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 180

{
  "client_id" : "5b20b042-5acf-4a55-b070-928a2ddd153a",
  "client_secret" : "WJd3kKyCauUX0f7SHZwuiuHVcxwfXEFjUwS57omFbzGfRFK54Z9IxFjCMuEcyNJA",
  "client_secret_expires_at" : 0
}

Renew API key

A POST request to renew API key on registered TPP

Path parameters

Table 5. /oauth2/register/{client_id}/renewKey
Parameter Description

client_id

client_id

Response fields

Path Type Description

client_id

String

Max 36. The client_id assigned by the application. This ID starts the authentication process and communication is decoded in the replacement of code and refresh_token.

api_key

String

API key

Example

POST /oauth2/register/5b20b042-5acf-4a55-b070-928a2ddd153a/renewKey HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-ClientCert: -----BEGIN CERTIFICATE-----
MIIECTCCAvGgAwIBAgIIZq/pqRBIgNkwDQYJKoZIhvcNAQELBQAwejELMAkGA1UE
BhMCQ1oxFzAVBgNVBAgTDkN6ZWNoIFJlcHVibGljMQ8wDQYDVQQHEwZQcmFndWUx
GTAXBgNVBAoTEEV4cG9iYW5rIENaIGEucy4xCzAJBgNVBAsTAklUMRkwFwYDVQQD
ExBFeHBvYmFuayBSb290IENBMB4XDTE5MTIyMDE2MzIwMFoXDTI2MDUyNTA1MDQw
MFowgaoxCzAJBgNVBAYTAkNaMRcwFQYDVQQIEw5DemVjaCBSZXB1YmxpYzEPMA0G
A1UEBxMGUHJhZ3VlMRkwFwYDVQQKExBFeHBvYmFuayBDWiBhLnMuMQswCQYDVQQL
EwJJVDEQMA4GA1UEAxMHbWFpbGtpdDEnMCUGCSqGSIb3DQEJARYYaXRfb3BlcmF0
b3JzQGV4cG9iYW5rLmN6MQ4wDAYDVQQMEwVwb3BpczCCASIwDQYJKoZIhvcNAQEB
BQADggEPADCCAQoCggEBAL3Zmcp7HuX/RGPONU03t55hWXXoFoc1hAGvKKBcsqq4
+Vsk4731+Q/Qqz+FJ71t3eb1vdH/R0fmSYqmnVUQLGdYMa0FygRVtyJYrk2lFGz0
cYm2QPKaZ5ZaBs4kISddv3eoTl6q3Y/4Nmpt3AaFiDhUuVfCqPo2Nzi4YE8+0afw
6o4aAQg7/tpC7oXOpJyX7K2jv/tnwql8ZzVtW2s0K9WAJc64R7XYy0S1HCU38r8M
XunQeK/kIbavL9zjBVHUKUuOl+th6GHPIUHCCL3QnvMDLrY/W/bw+Zji/dfnbEZq
+AqgazkJnB8R8KmxlVWkrN/WDDQhD2lWs1kYp3HRAAsCAwEAAaNiMGAwHQYDVR0O
BBYEFAeVLxjkSNDEIbAzSTu5cGz2mFqeMB8GA1UdIwQYMBaAFFYWKyIL6yB09UI0
HVQZf4RQ+PIqMB4GCWCGSAGG+EIBDQQRFg94Y2EgY2VydGlmaWNhdGUwDQYJKoZI
hvcNAQELBQADggEBAMA/o80FGAYLqsacjcmfwVysMc7WUSNWFCaAuM0IjvlLzUj1
rw8joh21HaUsR0g9ewrHuK9cXZFhprof0aeNJeH+HAaro+0KOKrAQKBOmhZoMDV6
AOi2VbV8ge37kzOIOiv5pQ3pXAiYUUAx8HUqwwTRS4DLlMiB8i4Xwy6a51AiMfOI
OIls3KcyOUY2b20ufw6LJKYDG80VZd5xWOShu8iG75kCeGir8AQfG4ir+uK7mzlH
CMTxL0c2wFlliFyqfFqKr6J+CVpqGIuD0uPqNAkhT46Vy2P1ioNiMff1RlpbiS9P
NLtuDmHAnyHTBE6NtdAAD0iGLbiLZDGMJVXsfWM=
-----END CERTIFICATE-----
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 140

{
  "client_id" : "5b20b042-5acf-4a55-b070-928a2ddd153a",
  "api_key" : "bw0QZG95jO7eYy9h2gEoBcq1wSsHtDYVnQQ3nFZyl8MQ1KWiFOVjms70kquN8Q0v"
}

Add new certificate for TPP

A POST request to add new Certificate

Path parameters

Table 6. /oauth2/register/{client_id}/addCertificate
Parameter Description

client_id

client_id

Request fields

Path Type Description

certificatePem

String

Required, PEM of new certificate

Example

POST /oauth2/register/5b20b042-5acf-4a55-b070-928a2ddd153a/addCertificate HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Content-Length: 1411
Host: localhost:8080

{
  "certificatePem" : "MIIECTCCAvGgAwIBAgIIZq/pqRBIgNkwDQYJKoZIhvcNAQELBQAwejELMAkGA1UEBhMCQ1oxFzAVBgNVBAgTDkN6ZWNoIFJlcHVibGljMQ8wDQYDVQQHEwZQcmFndWUxGTAXBgNVBAoTEEV4cG9iYW5rIENaIGEucy4xCzAJBgNVBAsTAklUMRkwFwYDVQQDExBFeHBvYmFuayBSb290IENBMB4XDTE5MTIyMDE2MzIwMFoXDTI2MDUyNTA1MDQwMFowgaoxCzAJBgNVBAYTAkNaMRcwFQYDVQQIEw5DemVjaCBSZXB1YmxpYzEPMA0GA1UEBxMGUHJhZ3VlMRkwFwYDVQQKExBFeHBvYmFuayBDWiBhLnMuMQswCQYDVQQLEwJJVDEQMA4GA1UEAxMHbWFpbGtpdDEnMCUGCSqGSIb3DQEJARYYaXRfb3BlcmF0b3JzQGV4cG9iYW5rLmN6MQ4wDAYDVQQMEwVwb3BpczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAL3Zmcp7HuX/RGPONU03t55hWXXoFoc1hAGvKKBcsqq4+Vsk4731+Q/Qqz+FJ71t3eb1vdH/R0fmSYqmnVUQLGdYMa0FygRVtyJYrk2lFGz0cYm2QPKaZ5ZaBs4kISddv3eoTl6q3Y/4Nmpt3AaFiDhUuVfCqPo2Nzi4YE8+0afw6o4aAQg7/tpC7oXOpJyX7K2jv/tnwql8ZzVtW2s0K9WAJc64R7XYy0S1HCU38r8MXunQeK/kIbavL9zjBVHUKUuOl+th6GHPIUHCCL3QnvMDLrY/W/bw+Zji/dfnbEZq+AqgazkJnB8R8KmxlVWkrN/WDDQhD2lWs1kYp3HRAAsCAwEAAaNiMGAwHQYDVR0OBBYEFAeVLxjkSNDEIbAzSTu5cGz2mFqeMB8GA1UdIwQYMBaAFFYWKyIL6yB09UI0HVQZf4RQ+PIqMB4GCWCGSAGG+EIBDQQRFg94Y2EgY2VydGlmaWNhdGUwDQYJKoZIhvcNAQELBQADggEBAMA/o80FGAYLqsacjcmfwVysMc7WUSNWFCaAuM0IjvlLzUj1rw8joh21HaUsR0g9ewrHuK9cXZFhprof0aeNJeH+HAaro+0KOKrAQKBOmhZoMDV6AOi2VbV8ge37kzOIOiv5pQ3pXAiYUUAx8HUqwwTRS4DLlMiB8i4Xwy6a51AiMfOIOIls3KcyOUY2b20ufw6LJKYDG80VZd5xWOShu8iG75kCeGir8AQfG4ir+uK7mzlHCMTxL0c2wFlliFyqfFqKr6J+CVpqGIuD0uPqNAkhT46Vy2P1ioNiMff1RlpbiS9PNLtuDmHAnyHTBE6NtdAAD0iGLbiLZDGMJVXsfWM="
}
HTTP/1.1 200 OK
Cache-Control: no-store

Authorization

A GET request to start authorization

Additional information

  • TPP approved scopes will be automatically used for user authorisation if request does not contain any scopes

Request parameters

Parameter Description

response_type

A mandatory parameter. It determines the authentication flow used. In this case, the code grant. For the authentication process it means that as the result of successful identification and authentication, a one-time code is expected instead of the access_token.

client_id

Unique identifier of the TPP application issued by the bank or the bank IDP. E.g., using the resource „0. Initialization/registration resource“

redirect_uri

URL where the authentication flow is directed at the end. The URL is determined on the issue of client_id and within the authentication, the parameter is validated against the URL introduced for client_id in the IDP system of the bank. The value should be identical to one of the values introduced by using the resource „0. Initialization/registration resource“.

scope

It is a field of applications required by the scope (authorization). In the case of PSD2, it may be the roles of aisp and pisp. E.g., if the TPP is the holder of both authorizations, here it may ask for its application one of them or both, see a request example

state

This parameter may enrich the redirect_uri on the redirecting. It serves for the delivery of information from the application through the authentication flow.

Response headers

Name Description

location

redirect url containing error description or code string in case of success

ERROR Example

GET /oauth2/auth?response_type=code&redirect_uri=https%253A%252F%252Ftpp.cz&client_id=5b20b042-5acf-4a55-b070-928a2ddd153a&scope=aisp&state=nejaky_state&redirect_uri=https%3A%2F%2Ftpp.cz HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Content-Type: application/json
Content-Length: 53

unauthorized_client - TPP client_id is not authorized

OK Example

GET /oauth2/auth?response_type=code&redirect_uri=https%253A%252F%252Ftpp.cz&client_id=5b20b042-5acf-4a55-b070-928a2ddd153a&scope=aisp&state=nejaky_state&redirect_uri=https%3A%2F%2Ftpp.cz HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Language: cs

Obtain a Token

A POST request to obtain a Token

Request parameters

Parameter Description

grant_type

'authorization_code'

client_id

ID of TPP application

redirect_uri

PSD2 - Redirect URL identical to the URL delivered in the authentication request. Expobank Mobile app - do not use

client_secret

Client secret - password/token issued by the bank IDP for the TPP application (client_id)

code

The authorization code returned from the authentication flow (code grant).

deviceId

optional, used only for Expobank Mobile app

tokenName

optional, used only for Expobank Mobile app

mobileOsType

optional, used only for Expobank Mobile app

mobileOsVersion

optional, used only for Expobank Mobile app

Request example

POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080

grant_type=authorization_code&code=A5J7ESFRPZQQTAV2FJ2P6LF2BFL3T4995N1BPM1Z4D2L6J8VJZ74VBK94HHNBFR2&client_id=068020f6-4631-4705-aae8-3ee6e9fb844b&client_secret=mUImYrCCxKupQ2Bs9NoF1gt5gNwqLu9IDjV0cfsF0lEGNO8qbwDs8a3BRXxYbjhS&redirect_uri=https%3A%2F%2Ftpp2.cz

Response - ERROR

Path Type Description

error

String

Error code

error_description

String

Error description

HTTP/1.1 401 Unauthorized
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 31

{
  "error" : "ACCESS_DENIED"
}

Response - OK

Path Type Description

access_token

String

A short-term (in some cases, a one-time) token that may be generated again using the refresh_token. The token serves for the authorization of the request at API.

expires_in

Number

A time left before the expiration of access_token - in seconds.

token_type

String

A token type, e.g., “Bearer”

acr

String

Verification level. It may have the values between 0 and 4. Default 3. The value „0“ corresponds to nonSCA.

refresh_token

String

refresh_token A long-term token issued based on replacement by the one-time code.

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 968

{
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI5Y2I2Y2JjNy03M2Q3LTRjYWMtYWQxNy1kNDQxYzhmZGM1YWUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjYwNSwiZXhwIjoxNjY1NjU2MjA1fQ.hAXt3mRCBv6rVfPs1OmYa5XaK3RE7QBy7pDM_eMBS5Q",
  "refresh_token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIzMjFiMjRiNC05NmFlLTQzMGQtYmQ2Yi1lYzdjM2I4ZjNkYWUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjYwNSwiZXhwIjoxNjczNDMyMjA1fQ.rzRrIjKcX-ayZrBHLObsXQF8R5XJuRsihSM0-JuO8Xo",
  "expires_in" : 3600,
  "token_type" : "Bearer",
  "acr" : "3"
}

Token refresh

A POST request to obtain a new access token from refresh token

Request parameters

Parameter Description

grant_type

'refresh_token'

client_id

ID of TPP application

refresh_token

Valid refresh_token for which the replacement is carried out, e.g. be9eef9b0af42c674d0b1c1128c37c2g

Response fields

Path Type Description

access_token

String

A short-term (in some cases, a one-time) token that may be generated again using the refresh_token. The token serves for the authorization of the request at API.

expires_in

Number

A time left before the expiration of access_token - in seconds.

token_type

String

A token type, e.g., “Bearer”

acr

String

Verification level. It may have the values between 0 and 4. Default 3. The value „0“ corresponds to nonSCA.

Example

POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080

grant_type=refresh_token&client_id=5b20b042-5acf-4a55-b070-928a2ddd153a&refresh_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6IjJiOTQ4YjhmLTNiYzItNGY2NC04YWRlLWMzZTU2ZTI2NTY5ZiIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiI1YjIwYjA0Mi01YWNmLTRhNTUtYjA3MC05MjhhMmRkZDE1M2EiLCJzY29wZXMiOlsicGlzcCIsImFpc3AiXSwiaWF0IjoxNjY1NjUyMjc5LCJleHAiOjE2NzM0MzE4Nzl9.kuz0MfUnpiMewyjiGplj0CenV600E_mX3H8P14WVzx0
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 495

{
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6IjU3NGU4YjZjLTUzMzUtNDFjZS04OTdjLTY5OThhNjI2NDdiMSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiI1YjIwYjA0Mi01YWNmLTRhNTUtYjA3MC05MjhhMmRkZDE1M2EiLCJzY29wZXMiOlsicGlzcCIsImFpc3AiXSwiaWF0IjoxNjY1NjUyMjgxLCJleHAiOjE2NjU2NTU4ODF9.wGH3ILFM-NsU2DhiZM_yblbHNZhRxLaRWY34XZ8e0cM",
  "expires_in" : 3600,
  "token_type" : "Bearer",
  "acr" : "3"
}

Token revoke

A POST request to revoke access or refresh token

Request parameters

Parameter Description

token

OAuth2 access or refresh token acquired based on the authentication process after the replacement by code or refresh token (in the case of access_token)

Example

POST /oauth2/revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6IjU3NGU4YjZjLTUzMzUtNDFjZS04OTdjLTY5OThhNjI2NDdiMSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiI1YjIwYjA0Mi01YWNmLTRhNTUtYjA3MC05MjhhMmRkZDE1M2EiLCJzY29wZXMiOlsicGlzcCIsImFpc3AiXSwiaWF0IjoxNjY1NjUyMjgxLCJleHAiOjE2NjU2NTU4ODF9.wGH3ILFM-NsU2DhiZM_yblbHNZhRxLaRWY34XZ8e0cM
Accept: application/json
Accept-Language: cs
Host: localhost:8080

token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6IjU3NGU4YjZjLTUzMzUtNDFjZS04OTdjLTY5OThhNjI2NDdiMSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiI1YjIwYjA0Mi01YWNmLTRhNTUtYjA3MC05MjhhMmRkZDE1M2EiLCJzY29wZXMiOlsicGlzcCIsImFpc3AiXSwiaWF0IjoxNjY1NjUyMjgxLCJleHAiOjE2NjU2NTU4ODF9.wGH3ILFM-NsU2DhiZM_yblbHNZhRxLaRWY34XZ8e0cM
HTTP/1.1 200 OK
Cache-Control: no-store

AISP & PISP Headers

Differences from COBS standard

  • API-key is required. While API-key is in COBS optional parameter, we use it as another security element, that can be repeatedly renewed by registered TPP.

Request Headers

Name Description

Accept-Language

language of the request, optional.

Content-Type

Specification of required transfer format. From the precondition of technical specification of this API standard, in this case, application/json format is primarily supported.

Authorization

The parameter is used to pass an access token of the authenticated user together with its type.

API-key

A required string issued to a communicating third party as the call identifier of that party primarily serving as a communication configuration element.

Accept

Max50Text No The Accept request HTTP header specifies which content types, expressed as MIME types, the client is able to understand.

+Accept-Language +

Max50Text No The Accept-Language request HTTP header specifies which languages the client is able to understand, and which locale variant is preferred. If no Accept-Language: is given, local country language is assumed. For example: Accept-Language: * Accept-Language: en-US, en;q=0.8

Content-Length

Number No The Content-Length entity-header field indicates the size of the entity-body, in decimal bytes, sent to the recipient.

Transfer-Encoding

Text Conditional The Transfer-Encoding general-header field specifies the form of encoding used to safely transfer the request payload to the ASPSP and back to TPP.

+User-IP-Address +

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

User-IP-Port

Max40Text No An element used to pass on information about what end-user IP port is using.

User-Device-OS

Max100Text No The element is used to forward information about the end user operating system used.

+User-User-Agent +

Max200Text No Contains information about the end-user web browser. The format should be the same as the standard HTTP parameter User-Agent.

User-Timestamp

DateTime No Local time on PSU device.

+User-Geo-Location +

Max100Text No 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) example: GEO:50.089354;14.400031

User-Device-ID

Text No It contains a unique identifier of end user equipment, if available. For example, a unique mobile device identifier (IMEI).

TPP-Name

The name of the original TPP that created the request. Eg. ‘Star corporation, a.s.’

TPP-Identification

The identification (licence number) of the original TPP that created the request. Eg. ‘CZ013574-15’

X-Request-ID

Max60Text Yes Unique identifier for each request specified by TPP. It is recommended to use a UUID format with a length of 36 to 60 characters.

Date

DateTime Yes Each request of a transaction contains the date and time at which the message was originated. In timestamp format.

+Action-ID +

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

User-Involved

Boolean Yes The flag identifies if the end user is online and the request was made based on his activity.

TPP-Name

Text Yes The name of the original TPP that created the request. Eg. ‘Star corporation, a.s.’.

TPP-Identification

Text No The identification (licence number) of the original TPP that created the request. Eg. ‘CZ013574-15’.

+Signature +

Text Conditional If the TPP signs the request, it contains a digital signature.

Digest

Text Conditional When an TPP includes a signature he also must include a 'Digest' header as defined in [RFC3230].

TPP-Signature-Certificate

Text Conditional The public TPP certificate used for signing the request, In base64 encoding (with the "BEGIN CERTIFICATE" and "END CERTIFICATE" markers).

Response Headers

Name Description

Content-Type

Specification of required transfer format. From the precondition of technical specification of this API standard, in this case, application/json format is primarily supported.

X-Request-ID

Max60Text Yes Unique identifier for each request specified by TPP. It is recommended to use a UUID format with a length of 36 to 60 characters.

Action-ID

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

AISP API

Account list

A GET request to get a list of accounts of a user

Additional information

  • element “nameI18N” contains name of the account named by user in internet banking. When the account name is not set the element “nameI18N” is not returned.

Request parameters

Parameter Description

page

Optional. It defines the required page number. Pages are numbered from 0. If the parameter is not specified, the API returns the first (zero) page.

size

Optional. It defines the required number of records on the page. If the parameter is not specified, the API returns the entire set.

sort

Optional. It defines a list of fields for sorting. The individual fields in the list are separated by a comma

order

Optional. It defines the sorting direction for each field listed in the sort parameter. Possible values are: - asc for ascending sorting, - desc for descending sorting. The individual sorting directions are separated by commas precisely as the field names in the sort parameter and are listed in the same order as the fields listed in the sort parameter.

Response fields

Path Type Description

pageNumber

Number

Number of current page

pageCount

Number

Total number of query pages

nextPage

Number

The number of the next page. If the current page is at the same time the last page of the list, then this parameter is not listed or is given with a null value.

pageSize

Number

Number of entries per page. This parameter can match the required size value from the query, except for the cases when it is the last page, or when the requested page range exceeded the maximum limit defined for the particular API resource.

totalCount

Number

Optional data about the total number of entries for all pages. If this value cannot be precisely determined, it is not stated.

accounts[].id

String

API Payment account identifier

accounts[].identification.iban

String

IBAN

accounts[].identification.other

String

Account number

accounts[].currency

String

Payer’s account currency

accounts[].servicer.bankCode

String

Bank code

accounts[].servicer.countryCode

String

Country code of the bank

accounts[].servicer.bic

String

BIC of the bank

accounts[].nameI18N

String

Account name

accounts[].productI18N

String

Product name

accounts[].ownersNames[]

Array

Owner names

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example #1
GET /accounts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:12 CEST
X-Request-ID: f79e912f-0d96-46a7-a568-3e460255219b
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiMDNkZTgyNS04NjljLTQ5N2MtYmMxNS1jOTkwNDU0ZTc2MWEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjIxMCwiZXhwIjoxNjY1NjU1ODEwfQ.Wkgd_m0BrfnqBJcAmaHAWBdLrnGClqn2nrbwSVpmfNM
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: f79e912f-0d96-46a7-a568-3e460255219b
Content-Length: 1240

{
  "pageNumber" : 0,
  "pageCount" : 1,
  "totalCount" : 3,
  "accounts" : [ {
    "id" : "D5C2960C-D29B-4B8C-AEDD-7736035754F6",
    "identification" : {
      "iban" : "CZ9640000000007255060015",
      "other" : "7255060015"
    },
    "currency" : "EUR",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Zaměstnanecký účet",
    "ownersNames" : [ "ZELENKA JAN" ]
  }, {
    "id" : "0A580141-DEC4-4DBC-84A2-E86578E77B84",
    "identification" : {
      "iban" : "CZ7440000000007255060023",
      "other" : "7255060023"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Neo Účet",
    "ownersNames" : [ "ZELENKA JAN" ]
  }, {
    "id" : "339382F0-2608-4E08-B9A6-4A28D1960790",
    "identification" : {
      "iban" : "CZ2140000000007255060007",
      "other" : "7255060007"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "nameI18N" : "My main current account",
    "productI18N" : "Zaměstnanecký účet",
    "ownersNames" : [ "ZELENKA JAN" ]
  } ]
}
Example #2 - sort currency
GET /accounts?sort=currency&order=asc HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:13 CEST
X-Request-ID: 9c21c748-d75f-4d52-8884-8f9cba30e849
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiMDNkZTgyNS04NjljLTQ5N2MtYmMxNS1jOTkwNDU0ZTc2MWEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjIxMCwiZXhwIjoxNjY1NjU1ODEwfQ.Wkgd_m0BrfnqBJcAmaHAWBdLrnGClqn2nrbwSVpmfNM
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 9c21c748-d75f-4d52-8884-8f9cba30e849
Content-Length: 1240

{
  "pageNumber" : 0,
  "pageCount" : 1,
  "totalCount" : 3,
  "accounts" : [ {
    "id" : "0A580141-DEC4-4DBC-84A2-E86578E77B84",
    "identification" : {
      "iban" : "CZ7440000000007255060023",
      "other" : "7255060023"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Neo Účet",
    "ownersNames" : [ "ZELENKA JAN" ]
  }, {
    "id" : "339382F0-2608-4E08-B9A6-4A28D1960790",
    "identification" : {
      "iban" : "CZ2140000000007255060007",
      "other" : "7255060007"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "nameI18N" : "My main current account",
    "productI18N" : "Zaměstnanecký účet",
    "ownersNames" : [ "ZELENKA JAN" ]
  }, {
    "id" : "D5C2960C-D29B-4B8C-AEDD-7736035754F6",
    "identification" : {
      "iban" : "CZ9640000000007255060015",
      "other" : "7255060015"
    },
    "currency" : "EUR",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Zaměstnanecký účet",
    "ownersNames" : [ "ZELENKA JAN" ]
  } ]
}
Example #1 - sort currency desc, identification.other asc
GET /accounts?sort=currency%252Cidentification.other&order=desc%252Casc&sort=currency%2Cidentification.other&order=desc%2Casc HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:14 CEST
X-Request-ID: 82ce965a-ab45-4be3-a717-9d9d8eaa1894
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiMDNkZTgyNS04NjljLTQ5N2MtYmMxNS1jOTkwNDU0ZTc2MWEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjIxMCwiZXhwIjoxNjY1NjU1ODEwfQ.Wkgd_m0BrfnqBJcAmaHAWBdLrnGClqn2nrbwSVpmfNM
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 82ce965a-ab45-4be3-a717-9d9d8eaa1894
Content-Length: 1240

{
  "pageNumber" : 0,
  "pageCount" : 1,
  "totalCount" : 3,
  "accounts" : [ {
    "id" : "D5C2960C-D29B-4B8C-AEDD-7736035754F6",
    "identification" : {
      "iban" : "CZ9640000000007255060015",
      "other" : "7255060015"
    },
    "currency" : "EUR",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Zaměstnanecký účet",
    "ownersNames" : [ "ZELENKA JAN" ]
  }, {
    "id" : "339382F0-2608-4E08-B9A6-4A28D1960790",
    "identification" : {
      "iban" : "CZ2140000000007255060007",
      "other" : "7255060007"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "nameI18N" : "My main current account",
    "productI18N" : "Zaměstnanecký účet",
    "ownersNames" : [ "ZELENKA JAN" ]
  }, {
    "id" : "0A580141-DEC4-4DBC-84A2-E86578E77B84",
    "identification" : {
      "iban" : "CZ7440000000007255060023",
      "other" : "7255060023"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Neo Účet",
    "ownersNames" : [ "ZELENKA JAN" ]
  } ]
}

Account balance

A GET request to get an account balance

Additional information

  • TOTAL_AVAILABLE_BALANCE = available balance (including overdraft and blocked transactions)

  • CURRENT_BALANCE = clear balance without overdraft and blocked transactions,

  • OPENING_BALANCE = current balance from end of the last banking day.

Path parameters

Table 7. /accounts/{id}/balance
Parameter Description

id

Requested account id

Response fields

Path Type Description

balances[].type.codeOrProprietary.code

String

Indicates the type of balance to which the balance information relates

balances[].creditLine.included

Boolean

True if any credit line is included in an account

balances[].creditLine.amount.value

Number

Credit line amount

balances[].creditLine.amount.currency

String

Credit line currency

balances[].amount.value

Number

Account total available balance

balances[].amount.currency

String

Balance (account) currency

balances[].creditDebitIndicator

String

One of DBIT, CRDT

balances[].date.dateTime

String

Date or date and time of the balance according to ISO 8601

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /accounts/339382F0-2608-4E08-B9A6-4A28D1960790/balance HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:19 CEST
X-Request-ID: ab982ad8-37dd-40af-99e7-a508d5d398c6
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiMDNkZTgyNS04NjljLTQ5N2MtYmMxNS1jOTkwNDU0ZTc2MWEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjIxMCwiZXhwIjoxNjY1NjU1ODEwfQ.Wkgd_m0BrfnqBJcAmaHAWBdLrnGClqn2nrbwSVpmfNM
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: ab982ad8-37dd-40af-99e7-a508d5d398c6
Content-Length: 872

{
  "balances" : [ {
    "type" : {
      "codeOrProprietary" : {
        "code" : "TOTAL_AVAILABLE_BALANCE"
      }
    },
    "amount" : {
      "value" : 71847.76,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "CRDT",
    "date" : {
      "dateTime" : "2022-10-13T09:10:19.456Z"
    }
  }, {
    "type" : {
      "codeOrProprietary" : {
        "code" : "CURRENT_BALANCE"
      }
    },
    "amount" : {
      "value" : 72847.76,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "CRDT",
    "date" : {
      "dateTime" : "2022-10-13T09:10:19.456Z"
    }
  }, {
    "type" : {
      "codeOrProprietary" : {
        "code" : "OPENING_BALANCE"
      }
    },
    "amount" : {
      "value" : 79615.76,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "CRDT",
    "date" : {
      "dateTime" : "2022-10-12T22:00:00.000Z"
    }
  } ]
}

Account transactions

A GET request to get account transactions

Additional information

  • if you use request without sort parameter, you cannot use paging. In this case transactions are sorted by processing order and response is faster.

  • when parameter “fromDate” or “toDate” is inccorect the nearest date will be used,

Path parameters

Table 8. /accounts/{id}/transactions
Parameter Description

id

Requested account id

Request parameters

Parameter Description

page

Optional. It defines the required page number. Pages are numbered from 0. If the parameter is not specified, the API returns the first (zero) page.

size

Optional. It defines the required number of records on the page. If the parameter is not specified, the API returns the entire set.

sort

Optional. It defines a list of fields for sorting. The individual fields in the list are separated by a comma

order

Optional. It defines the sorting direction for each field listed in the sort parameter. Possible values are: - asc for ascending sorting, - desc for descending sorting. The individual sorting directions are separated by commas precisely as the field names in the sort parameter and are listed in the same order as the fields listed in the sort parameter.

fromDate

Optional. Date and time of the start of required transaction history. According to ISO 8601.

toDate

Optional.Date and time of the end of required transaction history [inclusive]. According to ISO 8601.

Response fields

Path Type Description

pageNumber

Number

Number of current page

pageCount

Number

Total number of query pages

nextPage

Number

The number of the next page. If the current page is at the same time the last page of the list, then this parameter is not listed or is given with a null value.

pageSize

Number

Number of entries per page. This parameter can match the required size value from the query, except for the cases when it is the last page, or when the requested page range exceeded the maximum limit defined for the particular API resource.

totalCount

Number

Optional data about the total number of entries for all pages. If this value cannot be precisely determined, it is not stated.

transactions[].entryReference

String

Identification no. of the payment assigned by the bank.

transactions[].amount.value

Number

Payment amount in the account currency for which payment history is generated.

transactions[].amount.currency

String

Account currency.

transactions[].creditDebitIndicator

String

Indication of whether it is a debit payment or credit payment of the account. An expression of whether it is a debit or credit payment is marked with one of the codes. DBIT: to the debit of, CRDT: In other cases

transactions[].reversalIndicator

Boolean

Indication of whether it is a cancellation. An expression of whether it is a cancellation or not is marked with one of the codes. true: It is cancellation, false: It is not cancellation

transactions[].status

String

Item status (debited or credited payments) of the account from the point of view of the bank. The statement will present only posted items, with the constant BOOK, or blocked items, with the constant PDNG.

transactions[].bookingDate.date

String

Date of processing/posting of payment by bank in the format ISODate, or ISODateTime, i.e. YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss.sTZD.

transactions[].valueDate.date

String

Due date/payment foreign currency in the format ISODate, i.e. YYYY-MM-DD

transactions[].bankTransactionCode.proprietary.code

Number

The code of banking transaction according to the code list of the Czech Banking Association assigned to a specific payment based on the 1st to 3rd level of transaction code list according to the CBA Standard for camt.053.

transactions[].bankTransactionCode.proprietary.issuer

String

Identification of the code list issuer for banking transactions which acquires the value of the CBA (CBA constant).

transactions[].entryDetails.transactionDetails.references.messageIdentification

String

Assumed payment identification entered by the client on its initiation or order of the payment in the payment history.

transactions[].entryDetails.transactionDetails.references.accountServicerReference

String

A banking reference assigned to the payment, e.g., on initiation through direct banking services.

transactions[].entryDetails.transactionDetails.references.paymentInformationIdentification

String

Specific symbol, for card payments, the internal card number

transactions[].entryDetails.transactionDetails.references.mandateIdentification

String

Constant symbol

transactions[].entryDetails.transactionDetails.references.endToEndIdentification

String

Variable symbol for domestic payments, SEPA reference for SEPA payments

transactions[].entryDetails.transactionDetails.references.chequeNumber

String

For card transactions there is a card number with asterisks. The card no. is each time in the format xxxxxxxxxxxx1234.

transactions[].entryDetails.transactionDetails.amountDetails.instructedAmount.amount.value

Number

The original amount and currency of payment that was required by the client for transfer.

transactions[].entryDetails.transactionDetails.amountDetails.instructedAmount.amount.currency

String

Currency

transactions[].entryDetails.transactionDetails.amountDetails.counterValueAmount.amount.value

Number

The amount and currency of payment in the client account currency after conversion of amount that was required by the client for transfer.

transactions[].entryDetails.transactionDetails.amountDetails.counterValueAmount.amount.currency

String

Currency

transactions[].entryDetails.transactionDetails.amountDetails.counterValueAmount.currencyExchange.sourceCurrency

String

Client account currency (source/original currency/payer account currency for conversion payments).

transactions[].entryDetails.transactionDetails.amountDetails.counterValueAmount.currencyExchange.targetCurrency

String

Payment currency

transactions[].entryDetails.transactionDetails.amountDetails.counterValueAmount.currencyExchange.exchangeRate

Number

The exchange rate used to charge a payment.

transactions[].entryDetails.transactionDetails.charges.bearer

String

Indication of that payments will be charged to his debit; DEBT - all fees were paid by the payer, CRED – all fees were paid by the payee, SHAR – the fees are divided between the payer and the payee

transactions[].entryDetails.transactionDetails.relatedParties.debtor.name

String

The name of the payer. It is according to the payment direction, and filled in in the case of counterparty.

transactions[].entryDetails.transactionDetails.relatedParties.debtor.postalAddress.addressLine[]

String

Unstructured record of the payer’s postal address, up to 2 lines.

transactions[].entryDetails.transactionDetails.relatedParties.debtorAccount.identification.iban

String

Payer account no. in the international format of IBAN account no. It is accoring to he payment direction, and filled in in the case of counterparty

transactions[].entryDetails.transactionDetails.relatedParties.debtorAccount.identification.other.identification

String

The value of payer account no. in other/local format of account no.

transactions[].entryDetails.transactionDetails.relatedParties.creditor.name

String

Name of the payee. It is according to the payment direction, and filled in in the case of counterparty.

transactions[].entryDetails.transactionDetails.relatedParties.creditor.postalAddress.addressLine[]

String

Unstructured record of the payee’s postal address, up to 2 lines.

transactions[].entryDetails.transactionDetails.relatedParties.creditorAccount.identification.iban

String

Payee account no. in the international format of IBAN account no. It is according to the payment direction, and filled in in the case of counterparty.

transactions[].entryDetails.transactionDetails.relatedParties.creditorAccount.identification.other.identification

String

The value of payee’s account no. in other/local format of account no.

transactions[].entryDetails.transactionDetails.relatedAgents.debtorAgent.financialInstitutionIdentification.bic

String

BIC / SWIFT payer’s bank code. It is according to the payment direction, and filled in in the case of counterparty.

transactions[].entryDetails.transactionDetails.relatedAgents.debtorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

The value of payer’s bank code in local format.

transactions[].entryDetails.transactionDetails.relatedAgents.creditorAgent.financialInstitutionIdentification.bic

String

BIC / SWIFT payee’s bank code. It is according to the payment direction, and filled in in the case of counterparty.

transactions[].entryDetails.transactionDetails.relatedAgents.creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

The value of payee’s bank code in local format.

transactions[].entryDetails.transactionDetails.purpose.proprietary

String

Účel platby

transactions[].entryDetails.transactionDetails.remittanceInformation.unstructured

String

Message for payee (comment)

transactions[].entryDetails.transactionDetails.remittanceInformation.structured.creditorReferenceInformation.reference[]

Array

["VS:varSymb","KS:constSymb","SS:specSymb"]

transactions[].entryDetails.transactionDetails.additionalTransactionInformation

String

Text description of the transaction type.

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /accounts/339382F0-2608-4E08-B9A6-4A28D1960790/transactions?fromDate=2022-04-13&page=0&size=10 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:03 CEST
X-Request-ID: 76d8f52a-a0d1-4818-8082-b2976f9c2001
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI1NGM0OWViOS1jMzY1LTRhNGYtYTE1Zi00MTI5ODYyOWU3MjMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjIwMiwiZXhwIjoxNjY1NjU1ODAyfQ.I3pqbjGgdbUKumyxyoA6VjZjC2WgtXA6TEnTc1VyHPI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 76d8f52a-a0d1-4818-8082-b2976f9c2001
Content-Length: 21914

{
  "pageNumber" : 0,
  "nextPage" : 1,
  "pageSize" : 10,
  "transactions" : [ {
    "entryReference" : "001D11F222860005-TPSD004964331",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-10-13"
    },
    "valueDate" : {
      "date" : "2022-10-13"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004964331",
          "accountServicerReference" : "001D11F222860005",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001B11E222860001-TPSD004569392",
    "amount" : {
      "value" : 6666.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-10-13"
    },
    "valueDate" : {
      "date" : "2022-10-13"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004569392",
          "accountServicerReference" : "001B11E222860001",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 6666.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 6666.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "7192370015"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "4000"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "TestBatchTransaction",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Interní platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11F222860004-TIBD004964337",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-10-13"
    },
    "valueDate" : {
      "date" : "2022-10-13"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004964337",
          "accountServicerReference" : "001D11F222860004",
          "endToEndIdentification" : "2222222222",
          "paymentInformationIdentification" : "111111",
          "mandateIdentification" : "3390"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditor" : {
            "name" : "Nekdo"
          },
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "670100-2207248272"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "6210"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "Posilam penize",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:2222222222", "KS:3390", "SS:111111" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11F222860002-TIBD004964275",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-10-12"
    },
    "valueDate" : {
      "date" : "2022-10-12"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004964275",
          "accountServicerReference" : "001D11F222860002",
          "endToEndIdentification" : "2222222222",
          "paymentInformationIdentification" : "111111",
          "mandateIdentification" : "3390"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditor" : {
            "name" : "Nekdo"
          },
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "670100-2207248272"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "6210"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "Posilam penize",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:2222222222", "KS:3390", "SS:111111" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E222020002-TIBD004957304",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-07-21"
    },
    "valueDate" : {
      "date" : "2022-07-21"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004957304",
          "accountServicerReference" : "001D11E222020002",
          "endToEndIdentification" : "2222222222",
          "paymentInformationIdentification" : "111111",
          "mandateIdentification" : "3390"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditor" : {
            "name" : "Nekdo"
          },
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "670100-2207248272"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "6210"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "Posilam penize",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:2222222222", "KS:3390", "SS:111111" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E221890012-TIBD004939022",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-07-08"
    },
    "valueDate" : {
      "date" : "2022-07-08"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004939022",
          "accountServicerReference" : "001D11E221890012",
          "endToEndIdentification" : "2222222222",
          "paymentInformationIdentification" : "111111",
          "mandateIdentification" : "3390"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditor" : {
            "name" : "Nekdo"
          },
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "670100-2207248272"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "6210"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "Posilam penize",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:2222222222", "KS:3390", "SS:111111" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E221890010-TIBD004939020",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-07-08"
    },
    "valueDate" : {
      "date" : "2022-07-08"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004939020",
          "accountServicerReference" : "001D11E221890010",
          "endToEndIdentification" : "2222222222",
          "paymentInformationIdentification" : "111111",
          "mandateIdentification" : "3390"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditor" : {
            "name" : "Nekdo"
          },
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "670100-2207248272"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "6210"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "Posilam penize",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:2222222222", "KS:3390", "SS:111111" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E221890008-TIBD004939018",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-07-08"
    },
    "valueDate" : {
      "date" : "2022-07-08"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004939018",
          "accountServicerReference" : "001D11E221890008",
          "endToEndIdentification" : "2222222222",
          "paymentInformationIdentification" : "111111",
          "mandateIdentification" : "3390"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditor" : {
            "name" : "Nekdo"
          },
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "670100-2207248272"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "6210"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "Posilam penize",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:2222222222", "KS:3390", "SS:111111" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E221890006-TIBD004939016",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-07-08"
    },
    "valueDate" : {
      "date" : "2022-07-08"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004939016",
          "accountServicerReference" : "001D11E221890006",
          "endToEndIdentification" : "2222222222",
          "paymentInformationIdentification" : "111111",
          "mandateIdentification" : "3390"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditor" : {
            "name" : "Nekdo"
          },
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "670100-2207248272"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "6210"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "Posilam penize",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:2222222222", "KS:3390", "SS:111111" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E221890004-TIBD004939014",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2022-07-08"
    },
    "valueDate" : {
      "date" : "2022-07-08"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004939014",
          "accountServicerReference" : "001D11E221890004",
          "endToEndIdentification" : "2222222222",
          "paymentInformationIdentification" : "111111",
          "mandateIdentification" : "3390"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 1.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditor" : {
            "name" : "Nekdo"
          },
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "670100-2207248272"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "6210"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "Posilam penize",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:2222222222", "KS:3390", "SS:111111" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  } ]
}

Standing orders

A GET request to get standing orders

Path parameters

Parameter Description

page

Optional. It defines the required page number. Pages are numbered from 0. If the parameter is not specified, the API returns the first (zero) page.

size

Optional. It defines the required number of records on the page. If the parameter is not specified, the API returns the entire set.

sort

Optional. It defines a list of fields for sorting. The individual fields in the list are separated by a comma

order

Optional. It defines the sorting direction for each field listed in the sort parameter. Possible values are: - asc for ascending sorting, - desc for descending sorting. The individual sorting directions are separated by commas precisely as the field names in the sort parameter and are listed in the same order as the fields listed in the sort parameter.

Sorting

Sorting is possible by any parameter. Inner params defines by dots. Examples:

  • Sort by amount value: amount.instructedAmount.value

  • Sort by transaction identification: standingOrderIdentification.transactionIdentification

Possible order params: asc and desc

Request headers

Name Description

Accept-Language

language of the request, optional.

Content-Type

Specification of required transfer format. From the precondition of technical specification of this API standard, in this case, application/json format is primarily supported.

Authorization

The parameter is used to pass an access token of the authenticated user together with its type.

API-key

A required string issued to a communicating third party as the call identifier of that party primarily serving as a communication configuration element.

Accept

Max50Text No The Accept request HTTP header specifies which content types, expressed as MIME types, the client is able to understand.

+Accept-Language +

Max50Text No The Accept-Language request HTTP header specifies which languages the client is able to understand, and which locale variant is preferred. If no Accept-Language: is given, local country language is assumed. For example: Accept-Language: * Accept-Language: en-US, en;q=0.8

Content-Length

Number No The Content-Length entity-header field indicates the size of the entity-body, in decimal bytes, sent to the recipient.

Transfer-Encoding

Text Conditional The Transfer-Encoding general-header field specifies the form of encoding used to safely transfer the request payload to the ASPSP and back to TPP.

+User-IP-Address +

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

User-IP-Port

Max40Text No An element used to pass on information about what end-user IP port is using.

User-Device-OS

Max100Text No The element is used to forward information about the end user operating system used.

+User-User-Agent +

Max200Text No Contains information about the end-user web browser. The format should be the same as the standard HTTP parameter User-Agent.

User-Timestamp

DateTime No Local time on PSU device.

+User-Geo-Location +

Max100Text No 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) example: GEO:50.089354;14.400031

User-Device-ID

Text No It contains a unique identifier of end user equipment, if available. For example, a unique mobile device identifier (IMEI).

TPP-Name

The name of the original TPP that created the request. Eg. ‘Star corporation, a.s.’

TPP-Identification

The identification (licence number) of the original TPP that created the request. Eg. ‘CZ013574-15’

X-Request-ID

Max60Text Yes Unique identifier for each request specified by TPP. It is recommended to use a UUID format with a length of 36 to 60 characters.

Date

DateTime Yes Each request of a transaction contains the date and time at which the message was originated. In timestamp format.

+Action-ID +

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

User-Involved

Boolean Yes The flag identifies if the end user is online and the request was made based on his activity.

TPP-Name

Text Yes The name of the original TPP that created the request. Eg. ‘Star corporation, a.s.’.

TPP-Identification

Text No The identification (licence number) of the original TPP that created the request. Eg. ‘CZ013574-15’.

+Signature +

Text Conditional If the TPP signs the request, it contains a digital signature.

Digest

Text Conditional When an TPP includes a signature he also must include a 'Digest' header as defined in [RFC3230].

TPP-Signature-Certificate

Text Conditional The public TPP certificate used for signing the request, In base64 encoding (with the "BEGIN CERTIFICATE" and "END CERTIFICATE" markers).

Response fields

Path Type Description

pageNumber

Number

Number of current page

pageCount

Number

Total number of query pages

nextPage

Number

The number of the next page. If the current page is at the same time the last page of the list, then this parameter is not listed or is given with a null value.

pageSize

Number

Number of entries per page. This parameter can match the required size value from the query, except for the cases when it is the last page, or when the requested page range exceeded the maximum limit defined for the particular API resource.

totalCount

Number

Optional data about the total number of entries for all pages. If this value cannot be precisely determined, it is not stated.

standingOrders[].standingOrderIdentification

Object

Max35Text Standing order identification

standingOrders[].standingOrderIdentification.instructionIdentification

String

Max35Text Instruction identification

standingOrders[].standingOrderIdentification.endToEndIdentification

String

Max35Text End to end identification

standingOrders[].standingOrderIdentification.transactionIdentification

String

Max35Text Transaction identification

standingOrders[].amount

Object

STDO - AmountType3CZ, ESST - AmountType3CZ, XBST - AmountType3Choice

standingOrders[].amount.instructedAmount

Object

CurrencyAndAmount Amount and currency in the instruction

standingOrders[].amount.instructedAmount.value

Number

Amount Amount of the transfer

standingOrders[].amount.instructedAmount.currency

String

CurrencyCode Transfer Currency

standingOrders[].standingOrder

Object

Structure describing the parameters of the standing orders

standingOrders[].standingOrder.alias

String

Max140Text Description resp. the user-defined standing order payment name

standingOrders[].standingOrder.execution

Object

Features of execution a standing order for payment

standingOrders[].standingOrder.execution.mode

String

Max35Text The execution mode defines when or how standing order will be cancelled, processed the last time

standingOrders[].standingOrder.execution.modeDue

String

Max35Text The execution due mode defines how the date when order should be executed is specified

standingOrders[].standingOrder.execution.interval

String

Max10Text Execution interval defines how often order is executed

standingOrders[].standingOrder.execution.remitSkipCount

Number

Number, 1 - default, each remitType (e.g. day or month), 2 - each second remitType (e.g. day or month), 3 - and so on. Must be in interval from 1 to 10. If not set, default value is 1.

standingOrders[].debtorAccount

Object

CashAccount16CZ Payer’s account

standingOrders[].debtorAccount.id

String

API Payment account identifier

standingOrders[].debtorAccount.identification

Object

AccountIdentification4ChoiceCZ Identification of the payer’s account

standingOrders[].debtorAccount.identification.iban

String

IBAN2007Identifier Payer account number in IBAN format

standingOrders[].debtorAccount.identification.other

Object

GenericAccountIdentification1CZ Another payer account number format

standingOrders[].debtorAccount.identification.other.identification

String

Max34Text Payer account number in local BBAN format

standingOrders[].debtorAccount.currency

String

CurrencyCode ISO 4217 Payer’s account currency

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /standingorders?page=0&size=2 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:26 CEST
X-Request-ID: 3ebd8fc5-5f67-4fdf-94f1-8b994b389432
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI2YTM3MWI5Yy1iYjg4LTRlMWYtYWFiZC01YzAxYjIyNTJkMjAiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjIyNCwiZXhwIjoxNjY1NjU1ODI0fQ.BzDl4w-y0YTkxzPEWfJCUS2zO9AMkK5945yYZgR3Cvg
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 3ebd8fc5-5f67-4fdf-94f1-8b994b389432
Content-Length: 1387

{
  "pageNumber" : 0,
  "pageCount" : 213,
  "nextPage" : 1,
  "pageSize" : 2,
  "totalCount" : 426,
  "standingOrders" : [ {
    "standingOrderIdentification" : {
      "transactionIdentification" : "1454"
    },
    "amount" : {
      "instructedAmount" : {
        "value" : 22.0,
        "currency" : "CZK"
      }
    },
    "standingOrder" : {
      "alias" : "abcd",
      "execution" : {
        "mode" : "UNTIL_CANCELLATION",
        "modeDue" : "DUE_OR_NEXT_DAY_OF_MONTH",
        "interval" : "MONTHLY",
        "remitSkipCount" : 1
      }
    },
    "debtorAccount" : {
      "id" : "D5C2960C-D29B-4B8C-AEDD-7736035754F6",
      "identification" : {
        "iban" : "CZ9640000000007255060015"
      },
      "currency" : "EUR"
    }
  }, {
    "standingOrderIdentification" : {
      "transactionIdentification" : "3396"
    },
    "amount" : {
      "instructedAmount" : {
        "value" : 15100.0,
        "currency" : "CZK"
      }
    },
    "standingOrder" : {
      "alias" : "purpose",
      "execution" : {
        "mode" : "UNTIL_CANCELLATION",
        "modeDue" : "DUE_OR_NEXT_DAY_OF_MONTH",
        "interval" : "WEEKLY",
        "remitSkipCount" : 1
      }
    },
    "debtorAccount" : {
      "id" : "D5C2960C-D29B-4B8C-AEDD-7736035754F6",
      "identification" : {
        "iban" : "CZ9640000000007255060015"
      },
      "currency" : "EUR"
    }
  } ]
}

Example sort by amount ASC

GET /standingorders?page=2&size=2&sort=amount.instructedAmount.value&order=ASC HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:23 CEST
X-Request-ID: c5135457-4369-4136-9a45-f451752124f4
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJjY2ZlZTkzZC03NzQ4LTRlMTAtYmUzNC02M2Y0MTgwZTY5ZDUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjIyMSwiZXhwIjoxNjY1NjU1ODIxfQ.klkuRkjGG856BnJuDmv9I3KHPS8G3lH6BXjhoEpaUho
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: c5135457-4369-4136-9a45-f451752124f4
Content-Length: 1440

{
  "pageNumber" : 2,
  "pageCount" : 213,
  "nextPage" : 3,
  "pageSize" : 2,
  "totalCount" : 426,
  "standingOrders" : [ {
    "standingOrderIdentification" : {
      "transactionIdentification" : "8510"
    },
    "amount" : {
      "instructedAmount" : {
        "value" : 0.3,
        "currency" : "USD"
      }
    },
    "standingOrder" : {
      "alias" : "prvni swift trvalak",
      "execution" : {
        "mode" : "UNTIL_CANCELLATION",
        "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
        "interval" : "MONTHLY_END_OF_MONTH",
        "remitSkipCount" : 1
      }
    },
    "debtorAccount" : {
      "id" : "339382F0-2608-4E08-B9A6-4A28D1960790",
      "identification" : {
        "iban" : "CZ2140000000007255060007"
      },
      "currency" : "CZK"
    }
  }, {
    "standingOrderIdentification" : {
      "transactionIdentification" : "8514"
    },
    "amount" : {
      "instructedAmount" : {
        "value" : 0.3,
        "currency" : "USD"
      }
    },
    "standingOrder" : {
      "alias" : "prvni swift trvalak",
      "execution" : {
        "mode" : "UNTIL_CANCELLATION",
        "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
        "interval" : "MONTHLY_END_OF_MONTH",
        "remitSkipCount" : 1
      }
    },
    "debtorAccount" : {
      "id" : "339382F0-2608-4E08-B9A6-4A28D1960790",
      "identification" : {
        "iban" : "CZ2140000000007255060007"
      },
      "currency" : "CZK"
    }
  } ]
}

Example sort by currency ASC and amount DESC

GET /standingorders?page=0&size=2&sort=amount.instructedAmount.currency,amount.instructedAmount.value&order=asc,desc HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:32 CEST
X-Request-ID: f0c6ae98-c28e-4246-b374-e240b92e4078
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI2MzY1NjZkNS1hZWQwLTRmMjAtYmZmYy01ZDlhZjY2MzAzYTUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjIzMCwiZXhwIjoxNjY1NjU1ODMwfQ.cZmoJU_5xwR33yccruvPm3R7gvjOevXd8v6LQUVi9J8
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: f0c6ae98-c28e-4246-b374-e240b92e4078
Content-Length: 1399

{
  "pageNumber" : 0,
  "pageCount" : 213,
  "nextPage" : 1,
  "pageSize" : 2,
  "totalCount" : 426,
  "standingOrders" : [ {
    "standingOrderIdentification" : {
      "transactionIdentification" : "3396"
    },
    "amount" : {
      "instructedAmount" : {
        "value" : 15100.0,
        "currency" : "CZK"
      }
    },
    "standingOrder" : {
      "alias" : "purpose",
      "execution" : {
        "mode" : "UNTIL_CANCELLATION",
        "modeDue" : "DUE_OR_NEXT_DAY_OF_MONTH",
        "interval" : "WEEKLY",
        "remitSkipCount" : 1
      }
    },
    "debtorAccount" : {
      "id" : "D5C2960C-D29B-4B8C-AEDD-7736035754F6",
      "identification" : {
        "iban" : "CZ9640000000007255060015"
      },
      "currency" : "EUR"
    }
  }, {
    "standingOrderIdentification" : {
      "transactionIdentification" : "5160"
    },
    "amount" : {
      "instructedAmount" : {
        "value" : 1500.0,
        "currency" : "CZK"
      }
    },
    "standingOrder" : {
      "alias" : "Czech Mint Saving 2426",
      "execution" : {
        "mode" : "UNTIL_DATE",
        "modeDue" : "DUE_OR_NEXT_DAY_OF_MONTH",
        "interval" : "MONTHLY",
        "remitSkipCount" : 1
      }
    },
    "debtorAccount" : {
      "id" : "0A580141-DEC4-4DBC-84A2-E86578E77B84",
      "identification" : {
        "iban" : "CZ7440000000007255060023"
      },
      "currency" : "CZK"
    }
  } ]
}

PISP API

Additional information

Single signature

Possible scenarios

  • SMS_FEDERATED – user authorizes the payment on the bank page with SMS code that is send to his phone immediately after opening authorization bank page. After authorization is user redirected back to your URI.

  • SMS_TPP – SMS code is send to user phone immediately after sending Payment signing request. Code from SMS has to be sent from TPP to bank by Authorization initiation (III) request.

FEDERATED scenario

  1. New payment is created by New Payment request. Element “paymentIdentification .transactionIdentification” and “signInfo.signId” are returned in response. Possible scenarios for signature options are returned in element “scenarios”.

  2. URL for user authorization form is returned in element “href.href” by Authorization detail (I) request. As parameters is used “paymentIdentification .transactionIdentification” and “signInfo.signId”.

  3. In case of successful authorization redirected to URI with parameter state=COMPLETED.

TPP scenario

  1. New payment is created by New Payment request. Element “paymentIdentification .transactionIdentification” and “signInfo.signId” are returned in response. Possible scenarios for signature options are returned in element “scenarios”.

  2. Element “code.prefix” is returned in response to Authorization detail (I) request. As parameters is used “paymentIdentification .transactionIdentification” and “signInfo.signId”. Code.prefix is necessary to show to user in format PREFIX-[field for input client code].

  3. Client code has to be sent by Authorization initiation (III) request. In case of successful authorization the element “signInfo.state” contains value COMPLETED in response.

Joint signature

Joint signature can be used if two signatures of two different users are required to authorize the payment. Both users must be authenticated (enrolled) separately.

Joint signature is required if state=SECOND_SIGN_REQUIRED is returned in URI or element “signInfo.state” contains SECOND_SIGN_REQUIRED in response on Authorization initiation (I).

For the second user must be obtained a new “signId” by API POST /payments/{paymentID}/sign/ then continue by payment authorization by step 2 as described above.

Balance check (PISP)

A POST request to balance check. User authentification is required

Request fields

Path Type Description

exchangeIdentification

String

Max35Text Clear query identification, required

card.cardholderName

String

Max45Text Card holder name, optional

card.maskedPan

String

Max30Text Masked card number, optional

debtorAccount.identification.iban

String

IBAN2007Identifier Account number for charges in IBAN format

debtorAccount.currency

String

CurrencyCode, ISO 4217 Payer account currency, optional

authenticationMethod

String

Client verification method, see AuthenticationMethod enum in COBS for possible values, optional

merchant.identification

String

Merchant identification, optional

merchant.type

String

Merchant type, see COBS enum for possible values, optional

merchant.shortName

String

Max35Text Merchant name, optional

merchant.commonName

String

Max70Text Merchant name as stated in the payment receipt, optional

merchant.address

String

Max140Text Merchant address, optional

merchant.countryCode

String

CountryCode, ISO 3166 (2 alphanumeric characters code version) Merchant country, optional

merchant.merchantCategoryCode

String

Min3Max4Text, ISO 18245, Merchant code following the transaction type, optional

transactionDetails.totalAmount

Number

Balance query amount

transactionDetails.currency

String

Balance query currency

Response fields

Path Type Description

responseIdentification

Number

Unique identification of response to query, number

exchangeIdentification

String

Max35Text Clear query identification from request

response

String

APPR - approved, DECL - declined

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example ok, approved

POST /payments/balanceCheck HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:51 CEST
X-Request-ID: d039c3b9-e5ec-4cb1-8b19-db409351cffc
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhNDhlZTg0Zi1hMDlmLTRlYzItYjBlYy03YjAwNDRmNGY1OTMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI0OSwiZXhwIjoxNjY1NjU1ODQ5fQ.Emu4RZm7CZFjuUC3dojv58kZ1lIqEzZjIRx3bRYPTqU
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 628
Host: localhost:8080

{
  "exchangeIdentification" : "BC1665652251229",
  "card" : {
    "cardholderName" : "Jan Zelenka",
    "maskedPan" : "1234********6789"
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "authenticationMethod" : "NPIN",
  "merchant" : {
    "identification" : "471 16 129",
    "type" : "MERC",
    "shortName" : "NEOLUXOR",
    "commonName" : "Neoluxor s.r.o.",
    "address" : "Hlavní 5, Praha 1",
    "countryCode" : "CZ",
    "merchantCategoryCode" : "5192"
  },
  "transactionDetails" : {
    "currency" : "CZK",
    "totalAmount" : 1
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: d039c3b9-e5ec-4cb1-8b19-db409351cffc
Content-Length: 117

{
  "exchangeIdentification" : "BC1665652251229",
  "responseIdentification" : 1665652252030,
  "response" : "APPR"
}

New Payment

A POST request to enter a new payment.

Request fields

Path Type Description

paymentIdentification.instructionIdentification

String

Max35Text Instruction identification

paymentIdentification.endToEndIdentification

String

Max35Text End to end identification

paymentIdentification.transactionIdentification

String

Max35Text Transaction identification

paymentTypeInformation.instructionPriority

String

Priority2Code Instruction priority

paymentTypeInformation.serviceLevel

Object

ServiceLevel8CZ Service level

paymentTypeInformation.serviceLevel.code

String

ExternalServiceLevel1Code Service level code

paymentTypeInformation.categoryPurpose

Object

CategoryPurpose1Choice Category of the purpose of payment

paymentTypeInformation.categoryPurpose.code

String

ExternalCategoryPurpose1Code Payment purpose category code

paymentTypeInformation.categoryPurpose.proprietary

String

Max35Text Free format for the purpose of the payment purpose

amount.instructedAmount

Object

CurrencyAndAmount Amount and currency in the instruction

amount.instructedAmount.value

Number

Amount Amount of the transfer

amount.instructedAmount.currency

String

CurrencyCode Transfer Currency

amount.equivalentAmount

Object

CurrencyAndAmount Equivalent amount and currency

amount.equivalentAmount.value

Number

Amount Equivalent transaction amount

amount.equivalentAmount.currency

String

CurrencyCode Currency equivalent to transaction amount

requestedExecutionDate

String

ISODate Requested date of payment

exchangeRateInformation

Object

ExchangeRateInformation1 Contractual course

exchangeRateInformation.exchangeRate

Number

BaseOneRate Agreed exchange rate

exchangeRateInformation.rateType

String

ExchangeRate Type of agreed exchange rate

exchangeRateInformation.contractIdentification

String

Max35Text Identify the use of the agreed exchange rate

chargeBearer

String

ChargeBearerType1Code Fee payer

chargesAccount

Object

CashAccount16CZ Account for fees

chargesAccount.identification

Object

AccountIdentification4ChoiceCZ Identification of account number for fees

chargesAccount.identification.iban

String

IBAN2007Identifier Account number for charges in IBAN format

chargesAccount.currency

String

CurrencyCode ISO 4217 Account currency for fees

ultimateDebtor

Object

PartyIdentification32CZ1 Original payer

ultimateDebtor.name

String

Max70Text The name of the original payer

ultimateDebtor.postalAddress

Object

PostalAddress6CZ Postal address of the original payer

ultimateDebtor.postalAddress.streetName

String

Max70Text Street of original payer

ultimateDebtor.postalAddress.buildingNumber

String

Max16Text The original payer’s house number

ultimateDebtor.postalAddress.postCode

String

Max16Text The postal code of the original payer

ultimateDebtor.postalAddress.townName

String

Max35Text City of the original payer

ultimateDebtor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country of the original payer

ultimateDebtor.postalAddress.addressLine[]

Array

Max70Text Unstructured entry of the original payer’s address

ultimateDebtor.identification

Object

Party6Choice Identification of the original payer

ultimateDebtor.identification.organisationIdentification

Object

OrganisationIdentification4CZ Unambiguous identification of the original payer as organization / legal entity. either organizationalIdentification or privateIdentification

ultimateDebtor.identification.organisationIdentification.bicOrBei

String

BICIdentifier Identification of the original payer as organization / legal entity in the form of BIC or BEI code.

ultimateDebtor.identification.organisationIdentification.other

Object

GenericOrganisationIdentification1 Other identification of the original payer as organization / legal entity.

ultimateDebtor.identification.organisationIdentification.other.identification

String

Max35Text Other identification of the original payer as organization / legal entity in unstructured form.

ultimateDebtor.identification.organisationIdentification.other.schemeName

Object

OrganisationIdentificationSchemeName1CZ Document type for identifying the original payer as organization / legal entity.

ultimateDebtor.identification.organisationIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the original payer as organization / legal entity in free text format.

ultimateDebtor.identification.organisationIdentification.other.schemeName.issuer

String

Max35Text Document exhibitor for identification the original payer as organization / legal entity.

ultimateDebtor.identification.privateIdentification

Object

PersonIdentification5CZ Unambiguous identification of the original payer as a natural person. either organizationalIdentification or privateIdentification

ultimateDebtor.identification.privateIdentification.other

Object

GenericPersonIdentification1 Other identification of the original payer as a natural person in unstructured form.

ultimateDebtor.identification.privateIdentification.other.identification

String

Max35Text Other identification of the original payer as a natural person in unstructured form.

ultimateDebtor.identification.privateIdentification.other.schemeName

Object

PersonIdentificationSchemeName1Choice Document type to identify the original payer as a natural person.

ultimateDebtor.identification.privateIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the original payer as a physical person in free text format.

ultimateDebtor.identification.privateIdentification.other.schemeName.issuer

String

Max35Text Document exhibitor for identification the original payer as a natural person.

debtor

Object

PartyIdentification32CZ2 Payer.

debtor.name

String

Max70Text Payer name

debtor.postalAddress

Object

PostalAddress6CZ Postal address of the payer

debtor.postalAddress.streetName

String

Max70Text The street name used for the postal address of the payer.

debtor.postalAddress.buildingNumber

String

Max16Text The reference number used for the postal address of the payer.

debtor.postalAddress.postCode

String

Max16Text The postal code used for the postal address of the payer.

debtor.postalAddress.townName

String

Max35Text The city name used for the postal address of the payer.

debtor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) The country name used for the postal address of the payer.

debtor.postalAddress.addressLine[]

Array

Max70Text Unstructured payer postal address record.

debtorAccount

Object

CashAccount16CZ Payer’s account

debtorAccount.identification

Object

AccountIdentification4ChoiceCZ Identification of the payer’s account

debtorAccount.identification.iban

String

IBAN2007Identifier Payer account number in IBAN format

debtorAccount.identification.other

Object

GenericAccountIdentification1CZ Another payer account number format

debtorAccount.identification.other.identification

String

Max34Text Payer account number in local BBAN format

debtorAccount.currency

String

CurrencyCode ISO 4217 Payer’s account currency

intermediaryAgent1

Object

BranchAndFinancialInstitutionIdentification4CZ Intermediate 1

intermediaryAgent1.financialInstitutionIdentification

Object

FinancialInstitutionIdentification7CZ Identification of the financial institution

intermediaryAgent1.financialInstitutionIdentification.bic

String

BICIdentifier BIC / SWIFT bank code

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification

Object

ClearingSystemMemberIdentification2 Identify a participant in a clearing system

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification

Object

ClearingSystemIdentification2Choice Identification of the clearing system

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.code

String

ClearingSystemIdentification1Code Code

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.proprietary

String

Max35Text Free format

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

Max35Text Subscriber Clearing Code

intermediaryAgent1.financialInstitutionIdentification.name

String

Max70Text Name

intermediaryAgent1.financialInstitutionIdentification.postalAddress

Object

PostalAddress6CZ Postal address

intermediaryAgent1.financialInstitutionIdentification.postalAddress.streetName

String

Max70Text Street

intermediaryAgent1.financialInstitutionIdentification.postalAddress.buildingNumber

String

Max16Text Building number

intermediaryAgent1.financialInstitutionIdentification.postalAddress.postCode

String

Max16Text Zip code

intermediaryAgent1.financialInstitutionIdentification.postalAddress.townName

String

Max35Text City

intermediaryAgent1.financialInstitutionIdentification.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country code

intermediaryAgent1.financialInstitutionIdentification.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

intermediaryAgent1.financialInstitutionIdentification.other

Object

GenericFinancialIdentification1CZ Other bank identification

intermediaryAgent1.financialInstitutionIdentification.other.identification

String

Max35Text Local bank code

creditorAgent

Object

BranchAndFinancialInstitutionIdentification4CZ Bank of reciever

creditorAgent.financialInstitutionIdentification

Object

FinancialInstitutionIdentification7CZ Identification of the financial institution

creditorAgent.financialInstitutionIdentification.bic

String

BICIdentifier BIC / SWIFT bank code

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification

Object

ClearingSystemMemberIdentification2 Identifikace účastníka clearingového systému

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification

Object

ClearingSystemIdentification2Choice Identify a participant in a clearing system

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.code

String

ExternalClearingSystemIdentification1Code Code

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.proprietary

String

Max35Text Free format

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

Max35Text Subscriber Clearing Code

creditorAgent.financialInstitutionIdentification.name

String

Max105Text Name

creditorAgent.financialInstitutionIdentification.postalAddress

Object

PostalAddress6CZ Postal address

creditorAgent.financialInstitutionIdentification.postalAddress.streetName

String

Max70Text Street

creditorAgent.financialInstitutionIdentification.postalAddress.buildingNumber

String

Max16Text Building number

creditorAgent.financialInstitutionIdentification.postalAddress.postCode

String

Max16Text ZIP code

creditorAgent.financialInstitutionIdentification.postalAddress.townName

String

Max35Text City

creditorAgent.financialInstitutionIdentification.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country code

creditorAgent.financialInstitutionIdentification.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

creditorAgent.financialInstitutionIdentification.other

Object

GenericFinancialIdentification1C Other bank identification

creditorAgent.financialInstitutionIdentification.other.identification

String

Max35Text Local bank code

creditor

Object

PartyIdentification32CZ2 Payee

creditor.name

String

Max70Text Payee name

creditor.postalAddress

Object

PostalAddress6CZ Postal address

creditor.postalAddress.streetName

String

Max70Text Street

creditor.postalAddress.buildingNumber

String

Max16Text Building number

creditor.postalAddress.postCode

String

Max16Text ZIP code

creditor.postalAddress.townName

String

Max35Text City

creditor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country

creditor.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

creditorAccount

Object

CashAccount16CZ Payee account

creditorAccount.identification

Object

AccountIdentification4ChoiceCZ Payee Account Identification

creditorAccount.identification.iban

String

IBAN2007Identifier Account number in IBAN format

creditorAccount.identification.other

Object

GenericAccountIdentification1CZ Another account number format

creditorAccount.identification.other.identification

String

Max34Text Account number in local BBAN format

creditorAccount.currency

String

CurrencyCode ISO4217 Payee account currency

ultimateCreditor

Object

PartyIdentification32CZ1 The final payee

ultimateCreditor.name

String

Max70Text Name of the final payee

ultimateCreditor.postalAddress

Object

PostalAddress6CZ Postal address of the final payee

ultimateCreditor.postalAddress.streetName

String

Max70Text Street

ultimateCreditor.postalAddress.buildingNumber

String

Max16Text Building number

ultimateCreditor.postalAddress.postCode

String

Max16Text ZIP code

ultimateCreditor.postalAddress.townName

String

Max35Text City

ultimateCreditor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country

ultimateCreditor.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

ultimateCreditor.identification

Object

Party6Choice Identification of the final payee

ultimateCreditor.identification.organisationIdentification

Object

OrganisationIdentification4CZ Unambiguous identification of the final payee as an organization / legal entity. either organizationalIdentification or privateIdentification

ultimateCreditor.identification.organisationIdentification.bicOrBei

String

BICIdentifier Identification of the final payee as an organization / legal entity in the form of BIC or BEI code.

ultimateCreditor.identification.organisationIdentification.other

Object

GenericOrganisationIdentification1 Other identification of the final payee as organization / legal entity.

ultimateCreditor.identification.organisationIdentification.other.identification

String

Max35Text Other identification of parent payee as organization / legal entity in unstructured form.

ultimateCreditor.identification.organisationIdentification.other.schemeName

Object

OrganisationIdentificationSchemeName1CZ Document type for identifying the final payee as an organization / legal entity.

ultimateCreditor.identification.organisationIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the final payee as an organization / legal entity in free text format.

ultimateCreditor.identification.organisationIdentification.other.schemeName.issuer

String

Max35Text Document exhibitor for the final payee identification as an organization / legal entity.

ultimateCreditor.identification.privateIdentification

Object

PersonIdentification5CZ Unambiguous identification of the final payee as a natural person.

ultimateCreditor.identification.privateIdentification.other

Object

GenericPersonIdentification1 Other identification of the final payee as a natural person in unstructured form.

ultimateCreditor.identification.privateIdentification.other.identification

String

Max35Text Other identification of the final payee as a natural person in unstructured form.

ultimateCreditor.identification.privateIdentification.other.schemeName

Object

PersonIdentificationSchemeName1Choice Document type for identifying the final payee as a natural person.

ultimateCreditor.identification.privateIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the final payee as a physical person in free text format.

ultimateCreditor.identification.privateIdentification.other.schemeName.issuer

String

Max35Text Document exhibitor for the final payee identification as an natural person.

purpose

Object

Purpose2Choice Purpose of payment

purpose.code

String

ExternalPurpose1Code Purpose of payment code

purpose.proprietary

String

Max35Text Free form of payment purpose

instructionForNextAgent

String

Instruction code Instructions for the next bank

remittanceInformation

Object

RemittanceInformation5CZ Payment information

remittanceInformation.unstructured

String

Max140Text Unstructured message for the payee

remittanceInformation.structured

Object

StructuredRemittanceInformation7CZ Structured message for payee - variable, specific, and constant symbol

remittanceInformation.structured.creditorReferenceInformation

Object

CreditorReferenceInformation2CZ Payee reference information

remittanceInformation.structured.creditorReferenceInformation.reference[]

Array

CreditorReferenceInformation2CZ Value of VS, SS, CS - ["VS:varSymb","KS:konstSymb","SS:specSymb"]

signInfo

Object

Authorization info structure

signInfo.state

String

Transaction authorization status, one of OPEN, CODE_GENERATED, COMPLETED, SECOND_SIGN_REQUIRED

signInfo.signId

String

Identifier of the authorization process of a particular transaction.

signInfo.scenario

String

Selected authorization scenario

instructionStatus

String

Status code, Status of entered payment

statusChangeInfo

String

Information about change done in the bank

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED']

Response fields

Path Type Description

paymentIdentification.instructionIdentification

String

Max35Text Instruction identification

paymentIdentification.transactionIdentification

String

Max35Text Transaction identification

paymentTypeInformation.serviceLevel

Object

ServiceLevel8CZ Service level

paymentTypeInformation.serviceLevel.code

String

ExternalServiceLevel1Code Service level code

signInfo

Object

Authorization info structure

signInfo.state

String

Transaction authorization status, one of OPEN, CODE_GENERATED, COMPLETED, SECOND_SIGN_REQUIRED

signInfo.signId

String

Identifier of the authorization process of a particular transaction.

instructionStatus

String

Status code, Status of entered payment

statusChangeInfo

String

Information about change done in the bank

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED']

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Domestic #1

Request

POST /payments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:11:11 CEST
X-Request-ID: 82e642d4-43f3-4dd2-a80d-c195028df705
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI3NjgxM2JmYi04Y2MxLTQ4NjYtOWZmMC0wNjQxNThlMDg0YTIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI3MCwiZXhwIjoxNjY1NjU1ODcwfQ.H37-NtHOZQ1tmflRspBiKDl6XvrnE8xVg-HW_fbg0uI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 720
Host: localhost:8080

{
  "paymentIdentification" : {
    "instructionIdentification" : "1665652271688"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "NORM"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 100,
      "currency" : "CZK"
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ4820100000002100073281"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "FA 2353452",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 82e642d4-43f3-4dd2-a80d-c195028df705
Content-Length: 352

{
  "paymentIdentification" : {
    "transactionIdentification" : "TPSD004964394"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "DMCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "876bda1c-2958-40b5-bc75-401de44344f6"
  },
  "instructionStatus" : "ACTC"
}

Domestic with error

Request

POST /payments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:35 CEST
X-Request-ID: 504f1404-dabe-4969-b26c-486c13b830c8
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJkMDdlMTE3Mi1kODZmLTRhYTktYjY4Ni0zMmY1NDViMTYyMWYiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjIzNCwiZXhwIjoxNjY1NjU1ODM0fQ.leA_oD5X2CXGo3n-ZDBZZ9BDWWz842rQlpPcQHUY4NA
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 719
Host: localhost:8080

{
  "paymentIdentification" : {
    "instructionIdentification" : "1665652235933"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "XXX"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 100,
      "currency" : "CZK"
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ4820100000002100073281"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "FA 2353452",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
      }
    }
  }
}

Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
X-Request-ID: 504f1404-dabe-4969-b26c-486c13b830c8
Content-Type: application/json;charset=UTF-8
Content-Length: 234

{
  "errors" : [ {
    "error" : "FIELD_INVALID",
    "parameters" : {
      "ALLOWED_VALUES" : [ "NORM", "HIGH", "INST" ]
    },
    "scope" : "instructionPriority",
    "message" : "instructionPriority has invalid value XXX"
  } ]
}

Domestic #2

Request

POST /payments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:11:07 CEST
X-Request-ID: 9e9f617c-e846-46cf-afc9-4348504e22db
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI3OGM2Yjk4Yi1lNzBhLTQ0ZTktOTViYy1jYjY5MDc2ZmZiYjciLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI2NiwiZXhwIjoxNjY1NjU1ODY2fQ.SxRw72lsiuCvcYNNufES-_di_GAZEjNIBgc464vbcCs
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 641
Host: localhost:8080

{
  "paymentIdentification" : {
    "instructionIdentification" : "1665652266296"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "NORM"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1245.44,
      "currency" : "CZK"
    }
  },
  "requestedExecutionDate" : "2017-01-31",
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ6330300000000000000123"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "/VS/7418529630/SS/1234567890"
  }
}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 9e9f617c-e846-46cf-afc9-4348504e22db
Content-Length: 352

{
  "paymentIdentification" : {
    "transactionIdentification" : "TPSD004964392"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "DMCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "86e930ee-b1ce-4828-9391-6ad117033704"
  },
  "instructionStatus" : "ACTC"
}

SEPA

Request

POST /payments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:56 CEST
X-Request-ID: 2bd8c580-d0c7-4688-b0a5-c3da739c6f79
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIxZTRlYTM1NC0yOGM1LTRiNGUtYWFhOC01ODcyNzMzMTI0MmEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI1NCwiZXhwIjoxNjY1NjU1ODU0fQ.nsbA4MSHzwz4E9-i2p8Z-u2O-PIAEJpvENBWikrUn6M
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 1958
Host: localhost:8080

{
  "paymentIdentification" : {
    "instructionIdentification" : "1665652254944",
    "endToEndIdentification" : "NOTPROVIDED"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "HIGH"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1.45,
      "currency" : "EUR"
    }
  },
  "requestedExecutionDate" : "2017-01-31",
  "ultimateDebtor" : {
    "name" : "Karel Novák",
    "postalAddress" : {
      "streetName" : "Vodičkova",
      "buildingNumber" : "12",
      "postCode" : "12000",
      "townName" : "Praha 2",
      "country" : "CZ"
    },
    "identification" : {
      "privateIdentification" : {
        "other" : {
          "identification" : "1245789528",
          "schemeName" : {
            "proprietary" : "ID CARD",
            "issuer" : "OU Praha 2,CZ"
          }
        }
      }
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ9640000000007255060015"
    },
    "currency" : "EUR"
  },
  "creditorAgent" : {
    "financialInstitutionIdentification" : {
      "bic" : "MHBFDEFF"
    }
  },
  "creditor" : {
    "name" : "1. wiena investment",
    "postalAddress" : {
      "streetName" : "Reisnerstraße",
      "buildingNumber" : "20",
      "postCode" : "1030",
      "townName" : "Wiena",
      "country" : "AT"
    }
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "DE77503302002085734000"
    }
  },
  "ultimateCreditor" : {
    "name" : "Franz Schubert",
    "postalAddress" : {
      "streetName" : "Dianagasse",
      "buildingNumber" : "6",
      "postCode" : "1030",
      "townName" : "Wiena",
      "country" : "AT"
    },
    "identification" : {
      "privateIdentification" : {
        "other" : {
          "identification" : "12356879131",
          "schemeName" : {
            "proprietary" : "passport",
            "issuer" : "WIENA"
          }
        }
      }
    }
  },
  "purpose" : {
    "proprietary" : "sale of shares"
  }
}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 2bd8c580-d0c7-4688-b0a5-c3da739c6f79
Content-Length: 352

{
  "paymentIdentification" : {
    "transactionIdentification" : "TPSF000021318"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "ESCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "dec1471d-554f-4cd5-98f4-85a33734f2fc"
  },
  "instructionStatus" : "ACTC"
}

Foreign EEA

Request

POST /payments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:11:16 CEST
X-Request-ID: ccb37de3-22d9-4dc3-85bb-4c512cefee56
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhNWZkNDczNi0xNzJmLTQyOGQtOGQzNi1kYjcyMzU0NTU1NjIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI3NSwiZXhwIjoxNjY1NjU1ODc1fQ.vEfrSt9MSjQrcrFzqT8DP-lV_aJ-FUpOtYlWKfMHWRw
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 994
Host: localhost:8080

{
  "paymentIdentification" : {
    "instructionIdentification" : "1665652275212"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "NORM"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1.44,
      "currency" : "USD"
    }
  },
  "requestedExecutionDate" : "2017-01-31",
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAgent" : {
    "financialInstitutionIdentification" : {
      "bic" : "NDEAFIHH"
    }
  },
  "creditor" : {
    "name" : "Bohumil Hrabal",
    "postalAddress" : {
      "streetName" : "Na Hrázi",
      "buildingNumber" : "326/24",
      "postCode" : "18000",
      "townName" : "Praha 8",
      "country" : "CZ"
    }
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "FI6416603000117625",
      "other" : {
        "identification" : "204533335"
      }
    }
  },
  "remittanceInformation" : {
    "unstructured" : "fa 123546897"
  }
}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: ccb37de3-22d9-4dc3-85bb-4c512cefee56
Content-Length: 352

{
  "paymentIdentification" : {
    "transactionIdentification" : "TPSF000021319"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "XBCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "39c22098-e0e6-4b9f-8d5c-252b6ab6527d"
  },
  "instructionStatus" : "ACTC"
}

Foreign non EEA

Request

POST /payments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:53 CEST
X-Request-ID: ba31b53f-86aa-47c2-8fd2-bce9637f0cf1
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwODdjNjZjNi01NmZhLTRkN2UtOTE3My04NTA1ODFjODhlMmQiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI1MiwiZXhwIjoxNjY1NjU1ODUyfQ.ivyqDUkEoywoyFgtL_GjFb7aSaYkrbV3Ur9Yaiq3QSI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 1162
Host: localhost:8080

{
  "paymentIdentification" : {
    "instructionIdentification" : "1665652252295"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "NORM"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 0.44,
      "currency" : "GBP"
    }
  },
  "requestedExecutionDate" : "2017-01-31",
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAgent" : {
    "financialInstitutionIdentification" : {
      "bic" : "ABNYUS33",
      "name" : "New York Commercial Bank",
      "postalAddress" : {
        "streetName" : "Merrick Avenue615",
        "buildingNumber" : "61511590-6644",
        "postCode" : "11590-6644",
        "townName" : "WESTBURY, NY",
        "country" : "US"
      }
    }
  },
  "creditor" : {
    "name" : "First Hudson boat Inc.",
    "postalAddress" : {
      "streetName" : "Grand St",
      "buildingNumber" : "1256",
      "postCode" : "NY 11211",
      "townName" : "Brooklyn ,NY",
      "country" : "US"
    }
  },
  "creditorAccount" : {
    "identification" : {
      "other" : {
        "identification" : "123456789"
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: ba31b53f-86aa-47c2-8fd2-bce9637f0cf1
Content-Length: 352

{
  "paymentIdentification" : {
    "transactionIdentification" : "TPSF000021317"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "XBCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "4ab2270c-17d9-4f53-a417-0a2330e15cf9"
  },
  "instructionStatus" : "ACTC"
}

Payment status

A GET request to get an payment status. Request does not require the authorization of user/client as part of the API calling

Path parameters

Table 9. /payments/{paymentId}/status
Parameter Description

paymentId

Requested payment id

Response fields

Path Type Description

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

instructionStatus

String

Status code, Status of entered payment

Example

GET /payments/TPSD004964394/status HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:11:12 CEST
X-Request-ID: 1c6e69eb-5601-4fea-8036-1d2ff48463ec
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 1c6e69eb-5601-4fea-8036-1d2ff48463ec
Content-Length: 34

{
  "instructionStatus" : "ACTC"
}

Payment info

A GET request to get an information about payment.

Path parameters

Table 10. /payments/{paymentId}
Parameter Description

paymentId

Requested payment id

Response fields

Path Type Description

paymentIdentification.instructionIdentification

String

Max35Text Instruction identification

paymentIdentification.endToEndIdentification

String

Max35Text End to end identification

paymentIdentification.transactionIdentification

String

Max35Text Transaction identification

paymentTypeInformation.instructionPriority

String

Priority2Code Instruction priority

paymentTypeInformation.serviceLevel

Object

ServiceLevel8CZ Service level

paymentTypeInformation.serviceLevel.code

String

ExternalServiceLevel1Code Service level code

paymentTypeInformation.categoryPurpose

Object

CategoryPurpose1Choice Category of the purpose of payment

paymentTypeInformation.categoryPurpose.code

String

ExternalCategoryPurpose1Code Payment purpose category code

paymentTypeInformation.categoryPurpose.proprietary

String

Max35Text Free format for the purpose of the payment purpose

amount.instructedAmount

Object

CurrencyAndAmount Amount and currency in the instruction

amount.instructedAmount.value

Number

Amount Amount of the transfer

amount.instructedAmount.currency

String

CurrencyCode Transfer Currency

amount.equivalentAmount

Object

CurrencyAndAmount Equivalent amount and currency

amount.equivalentAmount.value

Number

Amount Equivalent transaction amount

amount.equivalentAmount.currency

String

CurrencyCode Currency equivalent to transaction amount

requestedExecutionDate

String

ISODate Requested date of payment

exchangeRateInformation

Object

ExchangeRateInformation1 Contractual course

exchangeRateInformation.exchangeRate

Number

BaseOneRate Agreed exchange rate

exchangeRateInformation.rateType

String

ExchangeRate Type of agreed exchange rate

exchangeRateInformation.contractIdentification

String

Max35Text Identify the use of the agreed exchange rate

chargeBearer

String

ChargeBearerType1Code Fee payer

chargesAccount

Object

CashAccount16CZ Account for fees

chargesAccount.identification

Object

AccountIdentification4ChoiceCZ Identification of account number for fees

chargesAccount.identification.iban

String

IBAN2007Identifier Account number for charges in IBAN format

chargesAccount.currency

String

CurrencyCode ISO 4217 Account currency for fees

ultimateDebtor

Object

PartyIdentification32CZ1 Original payer

ultimateDebtor.name

String

Max70Text The name of the original payer

ultimateDebtor.postalAddress

Object

PostalAddress6CZ Postal address of the original payer

ultimateDebtor.postalAddress.streetName

String

Max70Text Street of original payer

ultimateDebtor.postalAddress.buildingNumber

String

Max16Text The original payer’s house number

ultimateDebtor.postalAddress.postCode

String

Max16Text The postal code of the original payer

ultimateDebtor.postalAddress.townName

String

Max35Text City of the original payer

ultimateDebtor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country of the original payer

ultimateDebtor.postalAddress.addressLine[]

Array

Max70Text Unstructured entry of the original payer’s address

ultimateDebtor.identification

Object

Party6Choice Identification of the original payer

ultimateDebtor.identification.organisationIdentification

Object

OrganisationIdentification4CZ Unambiguous identification of the original payer as organization / legal entity. either organizationalIdentification or privateIdentification

ultimateDebtor.identification.organisationIdentification.bicOrBei

String

BICIdentifier Identification of the original payer as organization / legal entity in the form of BIC or BEI code.

ultimateDebtor.identification.organisationIdentification.other

Object

GenericOrganisationIdentification1 Other identification of the original payer as organization / legal entity.

ultimateDebtor.identification.organisationIdentification.other.identification

String

Max35Text Other identification of the original payer as organization / legal entity in unstructured form.

ultimateDebtor.identification.organisationIdentification.other.schemeName

Object

OrganisationIdentificationSchemeName1CZ Document type for identifying the original payer as organization / legal entity.

ultimateDebtor.identification.organisationIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the original payer as organization / legal entity in free text format.

ultimateDebtor.identification.organisationIdentification.other.schemeName.issuer

String

Max35Text Document exhibitor for identification the original payer as organization / legal entity.

ultimateDebtor.identification.privateIdentification

Object

PersonIdentification5CZ Unambiguous identification of the original payer as a natural person. either organizationalIdentification or privateIdentification

ultimateDebtor.identification.privateIdentification.other

Object

GenericPersonIdentification1 Other identification of the original payer as a natural person in unstructured form.

ultimateDebtor.identification.privateIdentification.other.identification

String

Max35Text Other identification of the original payer as a natural person in unstructured form.

ultimateDebtor.identification.privateIdentification.other.schemeName

Object

PersonIdentificationSchemeName1Choice Document type to identify the original payer as a natural person.

ultimateDebtor.identification.privateIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the original payer as a physical person in free text format.

ultimateDebtor.identification.privateIdentification.other.schemeName.issuer

String

Max35Text Document exhibitor for identification the original payer as a natural person.

debtor

Object

PartyIdentification32CZ2 Payer.

debtor.name

String

Max70Text Payer name

debtor.postalAddress

Object

PostalAddress6CZ Postal address of the payer

debtor.postalAddress.streetName

String

Max70Text The street name used for the postal address of the payer.

debtor.postalAddress.buildingNumber

String

Max16Text The reference number used for the postal address of the payer.

debtor.postalAddress.postCode

String

Max16Text The postal code used for the postal address of the payer.

debtor.postalAddress.townName

String

Max35Text The city name used for the postal address of the payer.

debtor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) The country name used for the postal address of the payer.

debtor.postalAddress.addressLine[]

Array

Max70Text Unstructured payer postal address record.

debtorAccount

Object

CashAccount16CZ Payer’s account

debtorAccount.identification

Object

AccountIdentification4ChoiceCZ Identification of the payer’s account

debtorAccount.identification.iban

String

IBAN2007Identifier Payer account number in IBAN format

debtorAccount.identification.other

Object

GenericAccountIdentification1CZ Another payer account number format

debtorAccount.identification.other.identification

String

Max34Text Payer account number in local BBAN format

debtorAccount.currency

String

CurrencyCode ISO 4217 Payer’s account currency

intermediaryAgent1

Object

BranchAndFinancialInstitutionIdentification4CZ Intermediate 1

intermediaryAgent1.financialInstitutionIdentification

Object

FinancialInstitutionIdentification7CZ Identification of the financial institution

intermediaryAgent1.financialInstitutionIdentification.bic

String

BICIdentifier BIC / SWIFT bank code

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification

Object

ClearingSystemMemberIdentification2 Identify a participant in a clearing system

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification

Object

ClearingSystemIdentification2Choice Identification of the clearing system

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.code

String

ClearingSystemIdentification1Code Code

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.proprietary

String

Max35Text Free format

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

Max35Text Subscriber Clearing Code

intermediaryAgent1.financialInstitutionIdentification.name

String

Max70Text Name

intermediaryAgent1.financialInstitutionIdentification.postalAddress

Object

PostalAddress6CZ Postal address

intermediaryAgent1.financialInstitutionIdentification.postalAddress.streetName

String

Max70Text Street

intermediaryAgent1.financialInstitutionIdentification.postalAddress.buildingNumber

String

Max16Text Building number

intermediaryAgent1.financialInstitutionIdentification.postalAddress.postCode

String

Max16Text Zip code

intermediaryAgent1.financialInstitutionIdentification.postalAddress.townName

String

Max35Text City

intermediaryAgent1.financialInstitutionIdentification.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country code

intermediaryAgent1.financialInstitutionIdentification.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

intermediaryAgent1.financialInstitutionIdentification.other

Object

GenericFinancialIdentification1CZ Other bank identification

intermediaryAgent1.financialInstitutionIdentification.other.identification

String

Max35Text Local bank code

creditorAgent

Object

BranchAndFinancialInstitutionIdentification4CZ Bank of reciever

creditorAgent.financialInstitutionIdentification

Object

FinancialInstitutionIdentification7CZ Identification of the financial institution

creditorAgent.financialInstitutionIdentification.bic

String

BICIdentifier BIC / SWIFT bank code

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification

Object

ClearingSystemMemberIdentification2 Identifikace účastníka clearingového systému

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification

Object

ClearingSystemIdentification2Choice Identify a participant in a clearing system

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.code

String

ExternalClearingSystemIdentification1Code Code

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.proprietary

String

Max35Text Free format

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

Max35Text Subscriber Clearing Code

creditorAgent.financialInstitutionIdentification.name

String

Max105Text Name

creditorAgent.financialInstitutionIdentification.postalAddress

Object

PostalAddress6CZ Postal address

creditorAgent.financialInstitutionIdentification.postalAddress.streetName

String

Max70Text Street

creditorAgent.financialInstitutionIdentification.postalAddress.buildingNumber

String

Max16Text Building number

creditorAgent.financialInstitutionIdentification.postalAddress.postCode

String

Max16Text ZIP code

creditorAgent.financialInstitutionIdentification.postalAddress.townName

String

Max35Text City

creditorAgent.financialInstitutionIdentification.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country code

creditorAgent.financialInstitutionIdentification.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

creditorAgent.financialInstitutionIdentification.other

Object

GenericFinancialIdentification1C Other bank identification

creditorAgent.financialInstitutionIdentification.other.identification

String

Max35Text Local bank code

creditor

Object

PartyIdentification32CZ2 Payee

creditor.name

String

Max70Text Payee name

creditor.postalAddress

Object

PostalAddress6CZ Postal address

creditor.postalAddress.streetName

String

Max70Text Street

creditor.postalAddress.buildingNumber

String

Max16Text Building number

creditor.postalAddress.postCode

String

Max16Text ZIP code

creditor.postalAddress.townName

String

Max35Text City

creditor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country

creditor.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

creditorAccount

Object

CashAccount16CZ Payee account

creditorAccount.identification

Object

AccountIdentification4ChoiceCZ Payee Account Identification

creditorAccount.identification.iban

String

IBAN2007Identifier Account number in IBAN format

creditorAccount.identification.other

Object

GenericAccountIdentification1CZ Another account number format

creditorAccount.identification.other.identification

String

Max34Text Account number in local BBAN format

creditorAccount.currency

String

CurrencyCode ISO4217 Payee account currency

ultimateCreditor

Object

PartyIdentification32CZ1 The final payee

ultimateCreditor.name

String

Max70Text Name of the final payee

ultimateCreditor.postalAddress

Object

PostalAddress6CZ Postal address of the final payee

ultimateCreditor.postalAddress.streetName

String

Max70Text Street

ultimateCreditor.postalAddress.buildingNumber

String

Max16Text Building number

ultimateCreditor.postalAddress.postCode

String

Max16Text ZIP code

ultimateCreditor.postalAddress.townName

String

Max35Text City

ultimateCreditor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country

ultimateCreditor.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

ultimateCreditor.identification

Object

Party6Choice Identification of the final payee

ultimateCreditor.identification.organisationIdentification

Object

OrganisationIdentification4CZ Unambiguous identification of the final payee as an organization / legal entity. either organizationalIdentification or privateIdentification

ultimateCreditor.identification.organisationIdentification.bicOrBei

String

BICIdentifier Identification of the final payee as an organization / legal entity in the form of BIC or BEI code.

ultimateCreditor.identification.organisationIdentification.other

Object

GenericOrganisationIdentification1 Other identification of the final payee as organization / legal entity.

ultimateCreditor.identification.organisationIdentification.other.identification

String

Max35Text Other identification of parent payee as organization / legal entity in unstructured form.

ultimateCreditor.identification.organisationIdentification.other.schemeName

Object

OrganisationIdentificationSchemeName1CZ Document type for identifying the final payee as an organization / legal entity.

ultimateCreditor.identification.organisationIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the final payee as an organization / legal entity in free text format.

ultimateCreditor.identification.organisationIdentification.other.schemeName.issuer

String

Max35Text Document exhibitor for the final payee identification as an organization / legal entity.

ultimateCreditor.identification.privateIdentification

Object

PersonIdentification5CZ Unambiguous identification of the final payee as a natural person.

ultimateCreditor.identification.privateIdentification.other

Object

GenericPersonIdentification1 Other identification of the final payee as a natural person in unstructured form.

ultimateCreditor.identification.privateIdentification.other.identification

String

Max35Text Other identification of the final payee as a natural person in unstructured form.

ultimateCreditor.identification.privateIdentification.other.schemeName

Object

PersonIdentificationSchemeName1Choice Document type for identifying the final payee as a natural person.

ultimateCreditor.identification.privateIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the final payee as a physical person in free text format.

ultimateCreditor.identification.privateIdentification.other.schemeName.issuer

String

Max35Text Document exhibitor for the final payee identification as an natural person.

purpose

Object

Purpose2Choice Purpose of payment

purpose.code

String

ExternalPurpose1Code Purpose of payment code

purpose.proprietary

String

Max35Text Free form of payment purpose

instructionForNextAgent

String

Instruction code Instructions for the next bank

remittanceInformation

Object

RemittanceInformation5CZ Payment information

remittanceInformation.unstructured

String

Max140Text Unstructured message for the payee

remittanceInformation.structured

Object

StructuredRemittanceInformation7CZ Structured message for payee - variable, specific, and constant symbol

remittanceInformation.structured.creditorReferenceInformation

Object

CreditorReferenceInformation2CZ Payee reference information

remittanceInformation.structured.creditorReferenceInformation.reference[]

Array

CreditorReferenceInformation2CZ Value of VS, SS, CS - ["VS:varSymb","KS:konstSymb","SS:specSymb"]

signInfo

Object

Authorization info structure

signInfo.state

String

Transaction authorization status, one of OPEN, CODE_GENERATED, COMPLETED, SECOND_SIGN_REQUIRED

signInfo.signId

String

Identifier of the authorization process of a particular transaction.

signInfo.scenario

String

Selected authorization scenario

instructionStatus

String

Status code, Status of entered payment

statusChangeInfo

String

Information about change done in the bank

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED']

sign2Info

Object

Authorization info structure of second signature

sign2Info.state

String

Transaction authorization status of second signature

sign2Info.signId

String

Identifier of the authorization process of second signature

sign2Info.scenario

String

Selected authorization scenario of second signature

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /payments/TPSD004964394 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:11:12 CEST
X-Request-ID: 18fdf33f-b41d-4f32-8b89-35ed15b07f18
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI3NjgxM2JmYi04Y2MxLTQ4NjYtOWZmMC0wNjQxNThlMDg0YTIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI3MCwiZXhwIjoxNjY1NjU1ODcwfQ.H37-NtHOZQ1tmflRspBiKDl6XvrnE8xVg-HW_fbg0uI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 18fdf33f-b41d-4f32-8b89-35ed15b07f18
Content-Length: 1001

{
  "paymentIdentification" : {
    "instructionIdentification" : "1665652271688",
    "transactionIdentification" : "TPSD004964394"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "NORM",
    "serviceLevel" : {
      "code" : "DMCT"
    }
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 100,
      "currency" : "CZK"
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ4820100000002100073281"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "FA 2353452",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
      }
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "876bda1c-2958-40b5-bc75-401de44344f6"
  },
  "instructionStatus" : "ACTC"
}

Payment delete

A DELETE request to delete payment - only if not processed yet

Path parameters

Table 11. /payments/{paymentId}
Parameter Description

paymentId

Requested payment id

Example

DELETE /payments/TPSD004964394 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:11:13 CEST
X-Request-ID: 44404a75-fd6a-417b-b358-8c372a8d4997
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI3NjgxM2JmYi04Y2MxLTQ4NjYtOWZmMC0wNjQxNThlMDg0YTIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI3MCwiZXhwIjoxNjY1NjU1ODcwfQ.H37-NtHOZQ1tmflRspBiKDl6XvrnE8xVg-HW_fbg0uI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 44404a75-fd6a-417b-b358-8c372a8d4997

Payment signing

Authorization detail (I)

A GET request to get payment authorization detail

Path parameters

Table 12. /payments/{paymentId}/sign/{signId}
Parameter Description

paymentId

Requested payment id

signId

signature id

Response fields

Path Type Description

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED']

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status, e.g. OPEN

signInfo.signId

String

Identifier of the authorization process of a particular transaction.

signInfo.scenario

String

Selected authorization scenario

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /payments/TPSD004964390/sign/481b2429-ba25-4432-9392-d005698cf40d HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:45 CEST
X-Request-ID: 5b56af2e-c3b6-461e-a0f3-6cb887c77179
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwZmQyYTdhNi02OGRlLTRiZTEtOWYwOS01ODFlNDIxMTYzMzUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI0MywiZXhwIjoxNjY1NjU1ODQzfQ.3PE2DYHA-g9leNeqoOg3hvjacBOucIko-Odwu6lefe4
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 5b56af2e-c3b6-461e-a0f3-6cb887c77179
Content-Length: 148

{
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "481b2429-ba25-4432-9392-d005698cf40d"
  }
}

Authorization initiation (II)

A POST request to generate signature

Path parameters

Table 13. /payments/{paymentId}/sign/{signId}
Parameter Description

paymentId

Requested payment id

signId

signature id

Request parameters

Parameter Description

testAuthCode

if true and application runs in non-production environment, then no SMS is send and auth.code value is always 0000

Request fields

Path Type Description

authorizationType

String

Code of required authorization (from authorization scenarios) - a selected scenario

redirectUrl

String

URL link or package of federated authorization call back address. This address is used by the federated bank authorization to redirect back to the TPP application after authorization is complete

Response fields

Path Type Description

authorizationType

String

Code of required authorization (from authorization scenarios) - a selected scenario

href

Object

Reference to call federated authorization

href.url

String

URL link or package of federated authorization

href.id

String

Possible id for calling federated authorization.

method

String

CMethod to use href link and federated authorization.

code

Object

Structure containing signing data for signing at TPP aplication

code.prefix

String

SMS or Token signing prefix

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status, e.g. OPEN

signInfo.signId

String

Identifier of the authorization process of a particular transaction. Up to 36 chars.

signInfo.scenario

String

Selected authorization scenario

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

POST /payments/TPSD004964390/sign/481b2429-ba25-4432-9392-d005698cf40d?testAuthCode=true HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:46 CEST
X-Request-ID: bfd486e9-8309-41a7-af2b-09d2daa9af7f
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwZmQyYTdhNi02OGRlLTRiZTEtOWYwOS01ODFlNDIxMTYzMzUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI0MywiZXhwIjoxNjY1NjU1ODQzfQ.3PE2DYHA-g9leNeqoOg3hvjacBOucIko-Odwu6lefe4
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 37
Host: localhost:8080

{
  "authorizationType" : "SMS_TPP"
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: bfd486e9-8309-41a7-af2b-09d2daa9af7f
Content-Length: 212

{
  "authorizationType" : "SMS_TPP",
  "code" : {
    "prefix" : "EEM"
  },
  "signInfo" : {
    "state" : "CODE_GENERATED",
    "signId" : "481b2429-ba25-4432-9392-d005698cf40d",
    "scenario" : "SMS_TPP"
  }
}

Authorization initiation (III)

A PUT request to confirm signature

Path parameters

Table 14. /payments/{paymentId}/sign/{signId}
Parameter Description

paymentId

Requested payment id

signId

signature id

Request fields

Path Type Description

code

Object

Structure of authorization code

code.code

String

authorization code value - one time password (SMS signing code, Token signing code)

Response fields

Path Type Description

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status, e.g. OPEN

signInfo.signId

String

Identifier of the authorization process of a particular transaction. Up to 36 chars.

signInfo.scenario

String

Selected authorization scenario

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

PUT /payments/TPSD004964390/sign/481b2429-ba25-4432-9392-d005698cf40d HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:47 CEST
X-Request-ID: fa4d4194-c07f-4943-9230-a6b839c49880
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwZmQyYTdhNi02OGRlLTRiZTEtOWYwOS01ODFlNDIxMTYzMzUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjI0MywiZXhwIjoxNjY1NjU1ODQzfQ.3PE2DYHA-g9leNeqoOg3hvjacBOucIko-Odwu6lefe4
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 40
Host: localhost:8080

{
  "code" : {
    "code" : "0000"
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: fa4d4194-c07f-4943-9230-a6b839c49880
Content-Length: 133

{
  "signInfo" : {
    "state" : "COMPLETED",
    "signId" : "481b2429-ba25-4432-9392-d005698cf40d",
    "scenario" : "SMS_TPP"
  }
}

New Standing order

A POST request to enter a standing order.

Additional information

  • when “alias” field is empty it will be filled automatically with account number

  • for every standing order with amount EUR 15 000 or more the reason for the payment is required to be stated in “purpose.proprietary” field

  • the SHAR value is set automatically to “chargeBearer” field for foreign payments when this field is not set

Differences from COBS standard

  • field “endToEndIdentification” is optional for SEPA payments

  • differences in “standingOrder” structure:

    • value DUE_LAST_DAY_OF_MONTH for “modeDue” field is not supported

    • new value MONTHLY_END_OF_MONTH is added for “interval” field that can be used in combination with valid values for “mode” field

    • “intervalDue” field is not supported

    • the new extra field “remitSkipCount” is added and defines repetition frequency. The valid values are 1-10 and it means every 1-10 for the value from field “interval”. Example: combination remitSkipCount=2 and interval=WEEKLY means, execute standing order every second week.

    • values IRREGURAL and BI-MONTHLY for “mode” field are note supported

    • values AFTER_MAX_ITERATION_EXCEEDED a MAX_AMOUNT_EXCEEDED for “mode” field are not supported

    • fields “validity.maxIterations” and “validity.maxAmount” are not supported

    • filed “exceptions” is not supported

  • “creditor.name” field is optional for domestic standing order

  • the length of the “creditor.name” field is 35 characters

Request fields

Path Type Description

standingOrderIdentification

Object

Max35Text Standing order identification

standingOrderIdentification.instructionIdentification

String

Max35Text Instruction identification

standingOrderIdentification.endToEndIdentification

String

Max35Text End to end identification

standingOrderIdentification.transactionIdentification

String

Max35Text Transaction identification

paymentTypeInformation

Object

PaymentTypeInformation19 Payment type information

paymentTypeInformation.instructionPriority

String

Priority2Code Instruction priority

paymentTypeInformation.serviceLevel

Object

ServiceLevel8CZ Service level

paymentTypeInformation.serviceLevel.code

String

ExternalServiceLevel1Code Service level code

paymentTypeInformation.categoryPurpose

Object

CategoryPurpose1Choice Category of the purpose of payment

paymentTypeInformation.categoryPurpose.code

String

ExternalCategoryPurpose1Code Payment purpose category code

paymentTypeInformation.categoryPurpose.proprietary

String

Max35Text Free format for the purpose of the payment purpose

amount

Object

STDO - AmountType3CZ, ESST - AmountType3CZ, XBST - AmountType3Choice

amount.instructedAmount

Object

CurrencyAndAmount Amount and currency in the instruction

amount.instructedAmount.value

Number

Amount Amount of the transfer

amount.instructedAmount.currency

String

CurrencyCode Transfer Currency

requestedExecutionDate

String

ISODate Requested date of payment

standingOrder

Object

Structure describing the parameters of the standing orders

standingOrder.alias

String

Max140Text Description resp. the user-defined standing order payment name

standingOrder.execution

Object

Features of execution a standing order for payment

standingOrder.execution.mode

String

Max35Text The execution mode defines when or how standing order will be cancelled, processed the last time

standingOrder.execution.modeDue

String

Max35Text The execution due mode defines how the date when order should be executed is specified

standingOrder.execution.interval

String

Max10Text Execution interval defines how often order is executed

standingOrder.execution.remitSkipCount

Number

Number, 1 - default, each remitType (e.g. day or month), 2 - each second remitType (e.g. day or month), 3 - and so on. Must be in interval from 1 to 10. If not set, default value is 1.

standingOrder.exceptions

Object

Elements defining exceptions to executing a standing order

standingOrder.exceptions.stoppages

Array

List of months where there is no payment (only applicable with interval IRREGULAR)

standingOrder.exceptions.breaks

Array

Elements defining exceptions to executing a standing order

standingOrder.exceptions.breaks[].validFromDate

String

Start date of one break period

standingOrder.exceptions.breaks[].validToDate

String

End date of one break period

standingOrder.validity

Object

Max250Text Elements restricting the validity of the standing order

standingOrder.validity.lastExecutionDate

String

ISODate Date when the last order will be processed. Null value responds to ending by the user.

exchangeRateInformation

Object

ExchangeRateInformation1 Contractual course

exchangeRateInformation.exchangeRate

Number

BaseOneRate Agreed exchange rate

exchangeRateInformation.rateType

String

ExchangeRate Type of agreed exchange rate

exchangeRateInformation.contractIdentification

String

Max35Text Identify the use of the agreed exchange rate

chargeBearer

String

ChargeBearerType1Code Fee payer

chargesAccount

Object

CashAccount16CZ Account for fees

chargesAccount.identification

Object

AccountIdentification4ChoiceCZ Identification of account number for fees

chargesAccount.identification.iban

String

IBAN2007Identifier Account number for charges in IBAN format

chargesAccount.currency

String

CurrencyCode ISO 4217 Account currency for fees

ultimateDebtor

Object

PartyIdentification32CZ1 Original payer

ultimateDebtor.name

String

Max70Text The name of the original payer

ultimateDebtor.postalAddress

Object

PostalAddress6CZ Postal address of the original payer

ultimateDebtor.postalAddress.streetName

String

Max70Text Street of original payer

ultimateDebtor.postalAddress.buildingNumber

String

Max16Text The original payer’s house number

ultimateDebtor.postalAddress.postCode

String

Max16Text The postal code of the original payer

ultimateDebtor.postalAddress.townName

String

Max35Text City of the original payer

ultimateDebtor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country of the original payer

ultimateDebtor.postalAddress.addressLine[]

Array

Max70Text Unstructured entry of the original payer’s address

ultimateDebtor.identification

Object

Party6Choice Identification of the original payer

ultimateDebtor.identification.organisationIdentification

Object

OrganisationIdentification4CZ Unambiguous identification of the original payer as organization / legal entity. either organizationalIdentification or privateIdentification

ultimateDebtor.identification.organisationIdentification.bicOrBei

String

BICIdentifier Identification of the original payer as organization / legal entity in the form of BIC or BEI code.

ultimateDebtor.identification.organisationIdentification.other

Object

GenericOrganisationIdentification1 Other identification of the original payer as organization / legal entity.

ultimateDebtor.identification.organisationIdentification.other.identification

String

Max35Text Other identification of the original payer as organization / legal entity in unstructured form.

ultimateDebtor.identification.organisationIdentification.other.schemeName

Object

OrganisationIdentificationSchemeName1CZ Document type for identifying the original payer as organization / legal entity.

ultimateDebtor.identification.organisationIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the original payer as organization / legal entity in free text format.

ultimateDebtor.identification.organisationIdentification.other.issuer

String

Max35Text Document exhibitor for identification the original payer as organization / legal entity.

ultimateDebtor.identification.privateIdentification

Object

PersonIdentification5CZ Unambiguous identification of the original payer as a natural person. either organizationalIdentification or privateIdentification

ultimateDebtor.identification.privateIdentification.other

Object

GenericPersonIdentification1 Other identification of the original payer as a natural person in unstructured form.

ultimateDebtor.identification.privateIdentification.other.identification

String

Max35Text Other identification of the original payer as a natural person in unstructured form.

ultimateDebtor.identification.privateIdentification.other.schemeName

Object

PersonIdentificationSchemeName1Choice Document type to identify the original payer as a natural person.

ultimateDebtor.identification.privateIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the original payer as a physical person in free text format.

ultimateDebtor.identification.privateIdentification.other.issuer

String

Max35Text Document exhibitor for identification the original payer as a natural person.

debtor

Object

PartyIdentification32CZ2 Payer.

debtor.name

String

Max70Text Payer name

debtor.postalAddress

Object

PostalAddress6CZ Postal address of the payer

debtor.postalAddress.streetName

String

Max70Text The street name used for the postal address of the payer.

debtor.postalAddress.buildingNumber

String

Max16Text The reference number used for the postal address of the payer.

debtor.postalAddress.postCode

String

Max16Text The postal code used for the postal address of the payer.

debtor.postalAddress.townName

String

Max35Text The city name used for the postal address of the payer.

debtor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) The country name used for the postal address of the payer.

debtor.postalAddress.addressLine[]

Array

Max70Text Unstructured payer postal address record.

debtorAccount

Object

CashAccount16CZ Payer’s account

debtorAccount.identification

Object

AccountIdentification4ChoiceCZ Identification of the payer’s account

debtorAccount.identification.iban

String

IBAN2007Identifier Payer account number in IBAN format

debtorAccount.identification.other

Object

GenericAccountIdentification1CZ Another payer account number format

debtorAccount.identification.other.identification

String

Max34Text Payer account number in local BBAN format

debtorAccount.currency

String

CurrencyCode ISO 4217 Payer’s account currency

intermediaryAgent1

Object

BranchAndFinancialInstitutionIdentification4CZ Intermediate 1

intermediaryAgent1.financialInstitutionIdentification

Object

FinancialInstitutionIdentification7CZ Identification of the financial institution

intermediaryAgent1.financialInstitutionIdentification.bic

String

BICIdentifier BIC / SWIFT bank code

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification

Object

ClearingSystemMemberIdentification2 Identify a participant in a clearing system

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification

Object

ClearingSystemIdentification2Choice Identification of the clearing system

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.code

String

ClearingSystemIdentification1Code Code

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.proprietary

String

Max35Text Free format

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

Max35Text Subscriber Clearing Code

intermediaryAgent1.financialInstitutionIdentification.name

String

Max70Text Name

intermediaryAgent1.financialInstitutionIdentification.postalAddress

Object

PostalAddress6CZ Postal address

intermediaryAgent1.financialInstitutionIdentification.postalAddress.streetName

String

Max70Text Street

intermediaryAgent1.financialInstitutionIdentification.postalAddress.buildingNumber

String

Max16Text Building number

intermediaryAgent1.financialInstitutionIdentification.postalAddress.postCode

String

Max16Text Zip code

intermediaryAgent1.financialInstitutionIdentification.postalAddress.townName

String

Max35Text City

intermediaryAgent1.financialInstitutionIdentification.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country code

intermediaryAgent1.financialInstitutionIdentification.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

intermediaryAgent1.financialInstitutionIdentification.other

Object

GenericFinancialIdentification1CZ Other bank identification

intermediaryAgent1.financialInstitutionIdentification.other.identification

String

Max35Text Local bank code

creditorAgent

Object

BranchAndFinancialInstitutionIdentification4CZ Bank of reciever

creditorAgent.financialInstitutionIdentification

Object

FinancialInstitutionIdentification7CZ Identification of the financial institution

creditorAgent.financialInstitutionIdentification.bic

String

BICIdentifier BIC / SWIFT bank code

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification

Object

ClearingSystemMemberIdentification2 Identifikace účastníka clearingového systému

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification

Object

ClearingSystemIdentification2Choice Identify a participant in a clearing system

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.code

String

ExternalClearingSystemIdentification1Code Code

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.proprietary

String

Max35Text Free format

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

Max35Text Subscriber Clearing Code

creditorAgent.financialInstitutionIdentification.name

String

Max105Text Name

creditorAgent.financialInstitutionIdentification.postalAddress

Object

PostalAddress6CZ Postal address

creditorAgent.financialInstitutionIdentification.postalAddress.streetName

String

Max70Text Street

creditorAgent.financialInstitutionIdentification.postalAddress.buildingNumber

String

Max16Text Building number

creditorAgent.financialInstitutionIdentification.postalAddress.postCode

String

Max16Text ZIP code

creditorAgent.financialInstitutionIdentification.postalAddress.townName

String

Max35Text City

creditorAgent.financialInstitutionIdentification.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country code

creditorAgent.financialInstitutionIdentification.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

creditorAgent.financialInstitutionIdentification.other

Object

GenericFinancialIdentification1C Other bank identification

creditorAgent.financialInstitutionIdentification.other.identification

String

Max35Text Local bank code

creditor

Object

PartyIdentification32CZ2 Payee

creditor.name

String

Max70Text Payee name

creditor.postalAddress

Object

PostalAddress6CZ Postal address

creditor.postalAddress.streetName

String

Max70Text Street

creditor.postalAddress.buildingNumber

String

Max16Text Building number

creditor.postalAddress.postCode

String

Max16Text ZIP code

creditor.postalAddress.townName

String

Max35Text City

creditor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country

creditor.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

creditorAccount

Object

CashAccount16CZ Payee account

creditorAccount.identification

Object

AccountIdentification4ChoiceCZ Payee Account Identification

creditorAccount.identification.iban

String

IBAN2007Identifier Account number in IBAN format

creditorAccount.identification.other

Object

GenericAccountIdentification1CZ Another account number format

creditorAccount.identification.other.identification

String

Max34Text Account number in local BBAN format

creditorAccount.currency

String

CurrencyCode ISO4217 Payee account currency

ultimateCreditor

Object

PartyIdentification32CZ1 The final payee

ultimateCreditor.name

String

Max70Text Name of the final payee

ultimateCreditor.postalAddress

Object

PostalAddress6CZ Postal address of the final payee

ultimateCreditor.postalAddress.streetName

String

Max70Text Street

ultimateCreditor.postalAddress.buildingNumber

String

Max16Text Building number

ultimateCreditor.postalAddress.postCode

String

Max16Text ZIP code

ultimateCreditor.postalAddress.townName

String

Max35Text City

ultimateCreditor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country

ultimateCreditor.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

ultimateCreditor.identification

Object

Party6Choice Identification of the final payee

ultimateCreditor.identification.organisationIdentification

Object

OrganisationIdentification4CZ Unambiguous identification of the final payee as an organization / legal entity. either organizationalIdentification or privateIdentification

ultimateCreditor.identification.organisationIdentification.bicOrBei

String

BICIdentifier Identification of the final payee as an organization / legal entity in the form of BIC or BEI code.

ultimateCreditor.identification.organisationIdentification.other

Object

GenericOrganisationIdentification1 Other identification of the final payee as organization / legal entity.

ultimateCreditor.identification.organisationIdentification.other.identification

String

Max35Text Other identification of parent payee as organization / legal entity in unstructured form.

ultimateCreditor.identification.organisationIdentification.other.schemeName

Object

OrganisationIdentificationSchemeName1CZ Document type for identifying the final payee as an organization / legal entity.

ultimateCreditor.identification.organisationIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the final payee as an organization / legal entity in free text format.

ultimateCreditor.identification.organisationIdentification.other.issuer

String

Max35Text Document exhibitor for the final payee identification as an organization / legal entity.

ultimateCreditor.identification.privateIdentification

Object

PersonIdentification5CZ Unambiguous identification of the final payee as a natural person.

ultimateCreditor.identification.privateIdentification.other

Object

GenericPersonIdentification1 Other identification of the final payee as a natural person in unstructured form.

ultimateCreditor.identification.privateIdentification.other.identification

String

Max35Text Other identification of the final payee as a natural person in unstructured form.

ultimateCreditor.identification.privateIdentification.other.schemeName

Object

PersonIdentificationSchemeName1Choice Document type for identifying the final payee as a natural person.

ultimateCreditor.identification.privateIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the final payee as a physical person in free text format.

ultimateCreditor.identification.privateIdentification.other.issuer

String

Max35Text Document exhibitor for the final payee identification as an natural person.

purpose

Object

Purpose2Choice Purpose of payment

purpose.code

String

ExternalPurpose1Code Purpose of payment code

purpose.proprietary

String

Max35Text Free form of payment purpose

instructionForNextAgent

String

Instruction code Instructions for the next bank

remittanceInformation

Object

RemittanceInformation5CZ Payment information

remittanceInformation.unstructured

String

Max140Text Unstructured message for the payee

remittanceInformation.structured

Object

StructuredRemittanceInformation7CZ Structured message for payee - variable, specific, and constant symbol

remittanceInformation.structured.creditorReferenceInformation

Object

CreditorReferenceInformation2CZ Payee reference information

remittanceInformation.structured.creditorReferenceInformation.reference[]

Array

CreditorReferenceInformation2CZ Value of VS, SS, CS - ["VS:varSymb","KS:konstSymb","SS:specSymb"]

instructionStatus

String

Status of entered payment

Response fields

Path Type Description

standingOrderIdentification

Object

Max35Text Standing order identification

standingOrderIdentification.transactionIdentification

String

Max35Text Transaction identification

paymentTypeInformation

Object

PaymentTypeInformation19 Payment type information

paymentTypeInformation.serviceLevel

Object

ServiceLevel8CZ Service level

paymentTypeInformation.serviceLevel.code

String

ExternalServiceLevel1Code Service level code

signInfo

Object

Authorization info structure

signInfo.state

String

Transaction authorization status, one of OPEN, CODE_GENERATED, COMPLETED, SECOND_SIGN_REQUIRED

signInfo.signId

String

Identifier of the authorization process of a particular transaction.

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED']

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Domestic standing order

Request

POST /standingorders HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:13:16 CEST
X-Request-ID: 59b5347f-cef4-4bc6-b771-3d67e5871612
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI5NTA0ZTJjYS1jMDA2LTRmYTgtOTE4YS0zYjkxMjhmMDZmNmIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjM5MywiZXhwIjoxNjY1NjU1OTkzfQ.M-Uzd3mNdbaRTsnm83oLQ3dZpx2SY1n22bL5Yt7Wqfw
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 955
Host: localhost:8080

{
  "standingOrderIdentification" : {
    "instructionIdentification" : "TEST_STANDING_ORDER_PSD2"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1500.0,
      "currency" : "CZK"
    }
  },
  "requestedExecutionDate" : "2222-09-08",
  "standingOrder" : {
    "alias" : "TEST_STANDING_ORDER_ALIAS",
    "execution" : {
      "mode" : "UNTIL_CANCELLATION",
      "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
      "interval" : "MONTHLY",
      "remitSkipCount" : 1
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ6330300000000000000123"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "Test sprava pro prijemce",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:1000", "KS:2000", "SS:3000" ]
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 59b5347f-cef4-4bc6-b771-3d67e5871612
Content-Length: 318

{
  "standingOrderIdentification" : {
    "transactionIdentification" : "14573"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "DMCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "4bab9cd5-2752-4e87-9d2c-7a9667b04af1"
  }
}

Foreign standing order

Request

POST /standingorders HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:12:33 CEST
X-Request-ID: c11533a5-c0a7-4062-9d29-f859d5563924
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIyYTgyNmY5NC0zYmY2LTRlOTUtYjRlZS05ZDU1ODNmNTUxYjEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjM1MSwiZXhwIjoxNjY1NjU1OTUxfQ.cgsyeYm8mYvI_n3s0ZozCJVhb0aYDG_at7HvSKIu6Xs
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 1107
Host: localhost:8080

{
  "standingOrderIdentification" : {
    "instructionIdentification" : "TEST_STANDING_ORDER_PSD2"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1500.0,
      "currency" : "CZK"
    }
  },
  "requestedExecutionDate" : "2222-09-08",
  "standingOrder" : {
    "alias" : "TEST_STANDING_ORDER_ALIAS",
    "execution" : {
      "mode" : "UNTIL_CANCELLATION",
      "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
      "interval" : "MONTHLY",
      "remitSkipCount" : 1
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAgent" : {
    "financialInstitutionIdentification" : {
      "bic" : "MHBFDEFF"
    }
  },
  "creditor" : {
    "name" : "Creditor name"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "DE77503302002085734000"
    },
    "currency" : "EUR"
  },
  "remittanceInformation" : {
    "unstructured" : "Test sprava pro prijemce",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:1000", "KS:2000", "SS:3000" ]
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: c11533a5-c0a7-4062-9d29-f859d5563924
Content-Length: 318

{
  "standingOrderIdentification" : {
    "transactionIdentification" : "14570"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "XBCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "eaefba27-c59f-474f-afcb-ebd7e05906be"
  }
}

Domestic with error, not supported execution exception

Request

POST /standingorders HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:12:35 CEST
X-Request-ID: 1c9011c3-e4eb-4053-878b-ae477bbd4c10
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwZjRlYTM0My02MmMwLTQ0YzUtODMxMi0zYjc2ZDA1NWQwOGEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjM1NCwiZXhwIjoxNjY1NjU1OTU0fQ.b0DJ7m6ho1mXjhqwO-O7gUtO5xFpENvP6wcDaoK1eTs
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 1022
Host: localhost:8080

{
  "standingOrderIdentification" : {
    "instructionIdentification" : "TEST_STANDING_ORDER_PSD2"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1500.0,
      "currency" : "CZK"
    }
  },
  "requestedExecutionDate" : "2222-09-08",
  "standingOrder" : {
    "alias" : "TEST_STANDING_ORDER_ALIAS",
    "execution" : {
      "mode" : "UNTIL_CANCELLATION",
      "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
      "interval" : "MONTHLY",
      "remitSkipCount" : 1
    },
    "exceptions" : {
      "stoppages" : [ "JUNE", "JULY" ]
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ6330300000000000000123"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "Test sprava pro prijemce",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:1000", "KS:2000", "SS:3000" ]
      }
    }
  }
}

Response

HTTP/1.1 500 Internal Server Error
Cache-Control: no-store
X-Request-ID: 1c9011c3-e4eb-4053-878b-ae477bbd4c10
Content-Type: application/json;charset=UTF-8
Content-Length: 133

{
  "errors" : [ {
    "error" : "NARR",
    "scope" : "standingOrder.exceptions",
    "message" : "Exceptions not supported"
  } ]
}

Domestic with error, not supported execution interval

Request

POST /standingorders HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:16:44 CEST
X-Request-ID: 32f1be94-8856-41d0-94ac-10bb3f0d2837
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4MTM0ZTcyNy0wZWVmLTRlMWMtOTcwMy1jMTU3YmE0N2RjYWMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjYwMSwiZXhwIjoxNjY1NjU2MjAxfQ.TgHlyjmugfAFUYPmRhaP0UsNCr-ryGJN5zEV4x2jZxQ
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 957
Host: localhost:8080

{
  "standingOrderIdentification" : {
    "instructionIdentification" : "TEST_STANDING_ORDER_PSD2"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1500.0,
      "currency" : "CZK"
    }
  },
  "requestedExecutionDate" : "2222-09-08",
  "standingOrder" : {
    "alias" : "TEST_STANDING_ORDER_ALIAS",
    "execution" : {
      "mode" : "UNTIL_CANCELLATION",
      "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
      "interval" : "IRREGULAR",
      "remitSkipCount" : 1
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ6330300000000000000123"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "Test sprava pro prijemce",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:1000", "KS:2000", "SS:3000" ]
      }
    }
  }
}

Response

HTTP/1.1 500 Internal Server Error
Cache-Control: no-store
X-Request-ID: 32f1be94-8856-41d0-94ac-10bb3f0d2837
Content-Type: application/json;charset=UTF-8
Content-Length: 143

{
  "errors" : [ {
    "error" : "NARR",
    "scope" : "standingOrder.execution.intervalDue",
    "message" : "IRREGULAR not supported"
  } ]
}

Domestic with error, wrong execution date

Request

POST /standingorders HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:13:51 CEST
X-Request-ID: 9745968b-77eb-4306-8452-ead41a370611
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4ODE0OWRiMi1iZjE2LTQwOTAtYmYxOC1hMzJmODVhMmU1OWUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjQyOSwiZXhwIjoxNjY1NjU2MDI5fQ.6m0I_YLaJ6euQ8mIb1Nz-HXzXAry0h5MRr9UiD2V48A
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 955
Host: localhost:8080

{
  "standingOrderIdentification" : {
    "instructionIdentification" : "TEST_STANDING_ORDER_PSD2"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1500.0,
      "currency" : "CZK"
    }
  },
  "requestedExecutionDate" : "1990-01-01",
  "standingOrder" : {
    "alias" : "TEST_STANDING_ORDER_ALIAS",
    "execution" : {
      "mode" : "UNTIL_CANCELLATION",
      "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
      "interval" : "MONTHLY",
      "remitSkipCount" : 1
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ6330300000000000000123"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "Test sprava pro prijemce",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:1000", "KS:2000", "SS:3000" ]
      }
    }
  }
}

Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
X-Request-ID: 9745968b-77eb-4306-8452-ead41a370611
Content-Type: application/json;charset=UTF-8
Content-Length: 160

{
  "errors" : [ {
    "error" : "DT01",
    "scope" : "requestedExecutionDate",
    "message" : "The required due date cannot be today or in the past."
  } ]
}

Domestic with error, not set end date of execution for parameter UNTIL_Date

Request

POST /standingorders HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:16:08 CEST
X-Request-ID: ca32a4af-8dea-4b72-b892-aa344a2b748d
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI0NTFiZWJkYS03NDU2LTRkYzEtYjA3Yi1jNTIyNjM2ZGFiYzAiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjU2NiwiZXhwIjoxNjY1NjU2MTY2fQ.Wh_6BXCBT7AiUR4AQngw87OQe227JT0dR7MaImc5IBI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 947
Host: localhost:8080

{
  "standingOrderIdentification" : {
    "instructionIdentification" : "TEST_STANDING_ORDER_PSD2"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1500.0,
      "currency" : "CZK"
    }
  },
  "requestedExecutionDate" : "2222-09-08",
  "standingOrder" : {
    "alias" : "TEST_STANDING_ORDER_ALIAS",
    "execution" : {
      "mode" : "UNTIL_DATE",
      "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
      "interval" : "MONTHLY",
      "remitSkipCount" : 1
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ6330300000000000000123"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "Test sprava pro prijemce",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:1000", "KS:2000", "SS:3000" ]
      }
    }
  }
}

Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
X-Request-ID: ca32a4af-8dea-4b72-b892-aa344a2b748d
Content-Type: application/json;charset=UTF-8
Content-Length: 154

{
  "errors" : [ {
    "error" : "FIELD_MISSING",
    "scope" : "standingOrder.validity",
    "message" : "Missing mandatory field in the request"
  } ]
}

Standing order detail

A GET request to get standing order details.

Path parameters

Table 15. /standingorders/{transactionIdentification}
Parameter Description

transactionIdentification

Requested transaction identification

Response fields

Path Type Description

standingOrderIdentification

Object

Max35Text Standing order identification

standingOrderIdentification.instructionIdentification

String

Max35Text Instruction identification

standingOrderIdentification.endToEndIdentification

String

Max35Text End to end identification

standingOrderIdentification.transactionIdentification

String

Max35Text Transaction identification

paymentTypeInformation

Object

PaymentTypeInformation19 Payment type information

paymentTypeInformation.instructionPriority

String

Priority2Code Instruction priority

paymentTypeInformation.serviceLevel

Object

ServiceLevel8CZ Service level

paymentTypeInformation.serviceLevel.code

String

ExternalServiceLevel1Code Service level code

paymentTypeInformation.categoryPurpose

Object

CategoryPurpose1Choice Category of the purpose of payment

paymentTypeInformation.categoryPurpose.code

String

ExternalCategoryPurpose1Code Payment purpose category code

paymentTypeInformation.categoryPurpose.proprietary

String

Max35Text Free format for the purpose of the payment purpose

amount

Object

STDO - AmountType3CZ, ESST - AmountType3CZ, XBST - AmountType3Choice

amount.instructedAmount

Object

CurrencyAndAmount Amount and currency in the instruction

amount.instructedAmount.value

Number

Amount Amount of the transfer

amount.instructedAmount.currency

String

CurrencyCode Transfer Currency

requestedExecutionDate

String

ISODate Requested date of payment

standingOrder

Object

Structure describing the parameters of the standing orders

standingOrder.alias

String

Max140Text Description resp. the user-defined standing order payment name

standingOrder.execution

Object

Features of execution a standing order for payment

standingOrder.execution.mode

String

Max35Text The execution mode defines when or how standing order will be cancelled, processed the last time

standingOrder.execution.modeDue

String

Max35Text The execution due mode defines how the date when order should be executed is specified

standingOrder.execution.interval

String

Max10Text Execution interval defines how often order is executed

standingOrder.execution.remitSkipCount

Number

Number, 1 - default, each remitType (e.g. day or month), 2 - each second remitType (e.g. day or month), 3 - and so on. Must be in interval from 1 to 10. If not set, default value is 1.

standingOrder.exceptions

Object

Elements defining exceptions to executing a standing order

standingOrder.exceptions.stoppages

Array

List of months where there is no payment (only applicable with interval IRREGULAR)

standingOrder.exceptions.breaks

Array

Elements defining exceptions to executing a standing order

standingOrder.exceptions.breaks[].validFromDate

String

Start date of one break period

standingOrder.exceptions.breaks[].validToDate

String

End date of one break period

standingOrder.validity

Object

Max250Text Elements restricting the validity of the standing order

standingOrder.validity.lastExecutionDate

String

ISODate Date when the last order will be processed. Null value responds to ending by the user.

exchangeRateInformation

Object

ExchangeRateInformation1 Contractual course

exchangeRateInformation.exchangeRate

Number

BaseOneRate Agreed exchange rate

exchangeRateInformation.rateType

String

ExchangeRate Type of agreed exchange rate

exchangeRateInformation.contractIdentification

String

Max35Text Identify the use of the agreed exchange rate

chargeBearer

String

ChargeBearerType1Code Fee payer

chargesAccount

Object

CashAccount16CZ Account for fees

chargesAccount.identification

Object

AccountIdentification4ChoiceCZ Identification of account number for fees

chargesAccount.identification.iban

String

IBAN2007Identifier Account number for charges in IBAN format

chargesAccount.currency

String

CurrencyCode ISO 4217 Account currency for fees

ultimateDebtor

Object

PartyIdentification32CZ1 Original payer

ultimateDebtor.name

String

Max70Text The name of the original payer

ultimateDebtor.postalAddress

Object

PostalAddress6CZ Postal address of the original payer

ultimateDebtor.postalAddress.streetName

String

Max70Text Street of original payer

ultimateDebtor.postalAddress.buildingNumber

String

Max16Text The original payer’s house number

ultimateDebtor.postalAddress.postCode

String

Max16Text The postal code of the original payer

ultimateDebtor.postalAddress.townName

String

Max35Text City of the original payer

ultimateDebtor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country of the original payer

ultimateDebtor.postalAddress.addressLine[]

Array

Max70Text Unstructured entry of the original payer’s address

ultimateDebtor.identification

Object

Party6Choice Identification of the original payer

ultimateDebtor.identification.organisationIdentification

Object

OrganisationIdentification4CZ Unambiguous identification of the original payer as organization / legal entity. either organizationalIdentification or privateIdentification

ultimateDebtor.identification.organisationIdentification.bicOrBei

String

BICIdentifier Identification of the original payer as organization / legal entity in the form of BIC or BEI code.

ultimateDebtor.identification.organisationIdentification.other

Object

GenericOrganisationIdentification1 Other identification of the original payer as organization / legal entity.

ultimateDebtor.identification.organisationIdentification.other.identification

String

Max35Text Other identification of the original payer as organization / legal entity in unstructured form.

ultimateDebtor.identification.organisationIdentification.other.schemeName

Object

OrganisationIdentificationSchemeName1CZ Document type for identifying the original payer as organization / legal entity.

ultimateDebtor.identification.organisationIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the original payer as organization / legal entity in free text format.

ultimateDebtor.identification.organisationIdentification.other.issuer

String

Max35Text Document exhibitor for identification the original payer as organization / legal entity.

ultimateDebtor.identification.privateIdentification

Object

PersonIdentification5CZ Unambiguous identification of the original payer as a natural person. either organizationalIdentification or privateIdentification

ultimateDebtor.identification.privateIdentification.other

Object

GenericPersonIdentification1 Other identification of the original payer as a natural person in unstructured form.

ultimateDebtor.identification.privateIdentification.other.identification

String

Max35Text Other identification of the original payer as a natural person in unstructured form.

ultimateDebtor.identification.privateIdentification.other.schemeName

Object

PersonIdentificationSchemeName1Choice Document type to identify the original payer as a natural person.

ultimateDebtor.identification.privateIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the original payer as a physical person in free text format.

ultimateDebtor.identification.privateIdentification.other.issuer

String

Max35Text Document exhibitor for identification the original payer as a natural person.

debtor

Object

PartyIdentification32CZ2 Payer.

debtor.name

String

Max70Text Payer name

debtor.postalAddress

Object

PostalAddress6CZ Postal address of the payer

debtor.postalAddress.streetName

String

Max70Text The street name used for the postal address of the payer.

debtor.postalAddress.buildingNumber

String

Max16Text The reference number used for the postal address of the payer.

debtor.postalAddress.postCode

String

Max16Text The postal code used for the postal address of the payer.

debtor.postalAddress.townName

String

Max35Text The city name used for the postal address of the payer.

debtor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) The country name used for the postal address of the payer.

debtor.postalAddress.addressLine[]

Array

Max70Text Unstructured payer postal address record.

debtorAccount

Object

CashAccount16CZ Payer’s account

debtorAccount.identification

Object

AccountIdentification4ChoiceCZ Identification of the payer’s account

debtorAccount.identification.iban

String

IBAN2007Identifier Payer account number in IBAN format

debtorAccount.identification.other

Object

GenericAccountIdentification1CZ Another payer account number format

debtorAccount.identification.other.identification

String

Max34Text Payer account number in local BBAN format

debtorAccount.currency

String

CurrencyCode ISO 4217 Payer’s account currency

intermediaryAgent1

Object

BranchAndFinancialInstitutionIdentification4CZ Intermediate 1

intermediaryAgent1.financialInstitutionIdentification

Object

FinancialInstitutionIdentification7CZ Identification of the financial institution

intermediaryAgent1.financialInstitutionIdentification.bic

String

BICIdentifier BIC / SWIFT bank code

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification

Object

ClearingSystemMemberIdentification2 Identify a participant in a clearing system

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification

Object

ClearingSystemIdentification2Choice Identification of the clearing system

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.code

String

ClearingSystemIdentification1Code Code

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.proprietary

String

Max35Text Free format

intermediaryAgent1.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

Max35Text Subscriber Clearing Code

intermediaryAgent1.financialInstitutionIdentification.name

String

Max70Text Name

intermediaryAgent1.financialInstitutionIdentification.postalAddress

Object

PostalAddress6CZ Postal address

intermediaryAgent1.financialInstitutionIdentification.postalAddress.streetName

String

Max70Text Street

intermediaryAgent1.financialInstitutionIdentification.postalAddress.buildingNumber

String

Max16Text Building number

intermediaryAgent1.financialInstitutionIdentification.postalAddress.postCode

String

Max16Text Zip code

intermediaryAgent1.financialInstitutionIdentification.postalAddress.townName

String

Max35Text City

intermediaryAgent1.financialInstitutionIdentification.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country code

intermediaryAgent1.financialInstitutionIdentification.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

intermediaryAgent1.financialInstitutionIdentification.other

Object

GenericFinancialIdentification1CZ Other bank identification

intermediaryAgent1.financialInstitutionIdentification.other.identification

String

Max35Text Local bank code

creditorAgent

Object

BranchAndFinancialInstitutionIdentification4CZ Bank of reciever

creditorAgent.financialInstitutionIdentification

Object

FinancialInstitutionIdentification7CZ Identification of the financial institution

creditorAgent.financialInstitutionIdentification.bic

String

BICIdentifier BIC / SWIFT bank code

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification

Object

ClearingSystemMemberIdentification2 Identifikace účastníka clearingového systému

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification

Object

ClearingSystemIdentification2Choice Identify a participant in a clearing system

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.code

String

ExternalClearingSystemIdentification1Code Code

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.clearingSystemIdentification.proprietary

String

Max35Text Free format

creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification.memberIdentification

String

Max35Text Subscriber Clearing Code

creditorAgent.financialInstitutionIdentification.name

String

Max105Text Name

creditorAgent.financialInstitutionIdentification.postalAddress

Object

PostalAddress6CZ Postal address

creditorAgent.financialInstitutionIdentification.postalAddress.streetName

String

Max70Text Street

creditorAgent.financialInstitutionIdentification.postalAddress.buildingNumber

String

Max16Text Building number

creditorAgent.financialInstitutionIdentification.postalAddress.postCode

String

Max16Text ZIP code

creditorAgent.financialInstitutionIdentification.postalAddress.townName

String

Max35Text City

creditorAgent.financialInstitutionIdentification.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country code

creditorAgent.financialInstitutionIdentification.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

creditorAgent.financialInstitutionIdentification.other

Object

GenericFinancialIdentification1C Other bank identification

creditorAgent.financialInstitutionIdentification.other.identification

String

Max35Text Local bank code

creditor

Object

PartyIdentification32CZ2 Payee

creditor.name

String

Max70Text Payee name

creditor.postalAddress

Object

PostalAddress6CZ Postal address

creditor.postalAddress.streetName

String

Max70Text Street

creditor.postalAddress.buildingNumber

String

Max16Text Building number

creditor.postalAddress.postCode

String

Max16Text ZIP code

creditor.postalAddress.townName

String

Max35Text City

creditor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country

creditor.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

creditorAccount

Object

CashAccount16CZ Payee account

creditorAccount.identification

Object

AccountIdentification4ChoiceCZ Payee Account Identification

creditorAccount.identification.iban

String

IBAN2007Identifier Account number in IBAN format

creditorAccount.identification.other

Object

GenericAccountIdentification1CZ Another account number format

creditorAccount.identification.other.identification

String

Max34Text Account number in local BBAN format

creditorAccount.currency

String

CurrencyCode ISO4217 Payee account currency

ultimateCreditor

Object

PartyIdentification32CZ1 The final payee

ultimateCreditor.name

String

Max70Text Name of the final payee

ultimateCreditor.postalAddress

Object

PostalAddress6CZ Postal address of the final payee

ultimateCreditor.postalAddress.streetName

String

Max70Text Street

ultimateCreditor.postalAddress.buildingNumber

String

Max16Text Building number

ultimateCreditor.postalAddress.postCode

String

Max16Text ZIP code

ultimateCreditor.postalAddress.townName

String

Max35Text City

ultimateCreditor.postalAddress.country

String

CountryCode, ISO3166 (2 alphanumeric characters code version) Country

ultimateCreditor.postalAddress.addressLine[]

Array

Max70Text Unstructured address entry

ultimateCreditor.identification

Object

Party6Choice Identification of the final payee

ultimateCreditor.identification.organisationIdentification

Object

OrganisationIdentification4CZ Unambiguous identification of the final payee as an organization / legal entity. either organizationalIdentification or privateIdentification

ultimateCreditor.identification.organisationIdentification.bicOrBei

String

BICIdentifier Identification of the final payee as an organization / legal entity in the form of BIC or BEI code.

ultimateCreditor.identification.organisationIdentification.other

Object

GenericOrganisationIdentification1 Other identification of the final payee as organization / legal entity.

ultimateCreditor.identification.organisationIdentification.other.identification

String

Max35Text Other identification of parent payee as organization / legal entity in unstructured form.

ultimateCreditor.identification.organisationIdentification.other.schemeName

Object

OrganisationIdentificationSchemeName1CZ Document type for identifying the final payee as an organization / legal entity.

ultimateCreditor.identification.organisationIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the final payee as an organization / legal entity in free text format.

ultimateCreditor.identification.organisationIdentification.other.issuer

String

Max35Text Document exhibitor for the final payee identification as an organization / legal entity.

ultimateCreditor.identification.privateIdentification

Object

PersonIdentification5CZ Unambiguous identification of the final payee as a natural person.

ultimateCreditor.identification.privateIdentification.other

Object

GenericPersonIdentification1 Other identification of the final payee as a natural person in unstructured form.

ultimateCreditor.identification.privateIdentification.other.identification

String

Max35Text Other identification of the final payee as a natural person in unstructured form.

ultimateCreditor.identification.privateIdentification.other.schemeName

Object

PersonIdentificationSchemeName1Choice Document type for identifying the final payee as a natural person.

ultimateCreditor.identification.privateIdentification.other.schemeName.proprietary

String

Max35Text Document type for identifying the final payee as a physical person in free text format.

ultimateCreditor.identification.privateIdentification.other.issuer

String

Max35Text Document exhibitor for the final payee identification as an natural person.

purpose

Object

Purpose2Choice Purpose of payment

purpose.code

String

ExternalPurpose1Code Purpose of payment code

purpose.proprietary

String

Max35Text Free form of payment purpose

instructionForNextAgent

String

Instruction code Instructions for the next bank

remittanceInformation

Object

RemittanceInformation5CZ Payment information

remittanceInformation.unstructured

String

Max140Text Unstructured message for the payee

remittanceInformation.structured

Object

StructuredRemittanceInformation7CZ Structured message for payee - variable, specific, and constant symbol

remittanceInformation.structured.creditorReferenceInformation

Object

CreditorReferenceInformation2CZ Payee reference information

remittanceInformation.structured.creditorReferenceInformation.reference[]

Array

CreditorReferenceInformation2CZ Value of VS, SS, CS - ["VS:varSymb","KS:konstSymb","SS:specSymb"]

instructionStatus

String

Status of entered payment

signInfo

Object

Authorization info structure

signInfo.state

String

Transaction authorization status, one of OPEN, CODE_GENERATED, COMPLETED, SECOND_SIGN_REQUIRED

signInfo.signId

String

Identifier of the authorization process of a particular transaction.

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED']

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /standingorders/14595 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:15:59 CEST
X-Request-ID: ae45707b-abba-4ec3-a622-0c0c5a72fda6
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhOTVjZmY2ZS01MGM1LTRkZGMtYTZjMi04YjA2ZWM5YjI3NzgiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjU1NiwiZXhwIjoxNjY1NjU2MTU2fQ.8GnhelZyN-RmHWvYv1DVo6vSn4a6NGGFKwXOqANmhck
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: ae45707b-abba-4ec3-a622-0c0c5a72fda6
Content-Length: 1260

{
  "standingOrderIdentification" : {
    "instructionIdentification" : "TEST_STANDING_ORDER_PSD2",
    "transactionIdentification" : "14595"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "NORM",
    "serviceLevel" : {
      "code" : "DMCT"
    }
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 1500.0,
      "currency" : "CZK"
    }
  },
  "requestedExecutionDate" : "2222-09-08",
  "standingOrder" : {
    "alias" : "TEST_STANDING_ORDER_ALIAS",
    "execution" : {
      "mode" : "UNTIL_CANCELLATION",
      "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
      "interval" : "MONTHLY",
      "remitSkipCount" : 1
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditor" : { },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ6330300000000000000123",
      "other" : { }
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "Test sprava pro prijemce",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:1000", "KS:2000", "SS:3000" ]
      }
    }
  },
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "37ebe70e-e496-4152-aba9-4f1151f42133"
  }
}

Standing order status

A GET request to get standing order status.

Path parameters

Table 16. /standingorders/{transactionIdentification}/status
Parameter Description

transactionIdentification

Requested transaction identification

Response fields

Path Type Description

instructionStatus

String

Status of entered payment

realizedPayments

Array

Array of transaction identificators

realizedPayments[].transactionIdentification

String

Identifier of established transaction

realizedPayments[].date

String

Due date/payment foreign currency in the format ISODate or ISODateTime.

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /standingorders/14599/status HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:16:21 CEST
X-Request-ID: 8af2547a-e9f6-4ab7-89fc-0187401ce3a0
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJlZTMwZWRiYS00MDlmLTRkMDgtOTFiZi0wNmQwOWFiYTVhMTMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjU3OCwiZXhwIjoxNjY1NjU2MTc4fQ.O9SnXIayACBrp-oXrc9eSYIlXShpIN0-ZDCJj6Il7JA
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 8af2547a-e9f6-4ab7-89fc-0187401ce3a0
Content-Length: 62

{
  "instructionStatus" : "ACTC",
  "realizedPayments" : [ ]
}

Example for not existing standing order

GET /standingorders/999999999 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:13:05 CEST
X-Request-ID: bd6e6435-710a-4b12-94aa-5a05ce08919f
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiNjRmNTE0Yi0xMGQ1LTQ0MTItOTVlNi1lMjExZDZhYmIxZTEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjM4MywiZXhwIjoxNjY1NjU1OTgzfQ.JEJ27TDJumIXXzl22nMT4gj1L3-Ma73Ic7OGEJ6FTwY
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 404 Not Found
Cache-Control: no-store
X-Request-ID: bd6e6435-710a-4b12-94aa-5a05ce08919f
Content-Type: application/json;charset=UTF-8
Content-Length: 112

{
  "errors" : [ {
    "error" : "TRANSACTION_MISSING",
    "message" : "Standing order does not exists"
  } ]
}

Standing order delete

A DELETE request to delete standing order

Path parameters

Table 17. /standingorders/{transactionIdentification}
Parameter Description

transactionIdentification

Requested transaction identification

Example

DELETE /standingorders/14572 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:13:12 CEST
X-Request-ID: efacc5aa-c5d8-4961-9482-133fb5324934
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI3ODFjYmQzMC0wYzA1LTQwOTYtODc1Zi04YzBiZWZkYTgxYTkiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjM4NywiZXhwIjoxNjY1NjU1OTg3fQ.H679SUoelgPrt9gKMXkvJ-B7T93qTsx1Z7fYDfHnI1Q
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: efacc5aa-c5d8-4961-9482-133fb5324934

Standing order update

A PUT request to change standing order

Additional information

  • to update the existing standing order you need to send not only the changed parameters, but also the existing ones

  • request for update of current standing order creates new standing order with new identification number. After authorization the current standing order is deleted

Path parameters

Table 18. /standingorders/{transactionIdentification}
Parameter Description

transactionIdentification

Requested transaction identification

Example

PUT /standingorders/14577 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:13:46 CEST
X-Request-ID: 37e08f30-ea1f-41e5-bbdb-aa4b4724b395
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI2YzYyYWQwZS0zOGU1LTRlNGQtOWFlNC0zZGJlZDc0NGZkOGMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjQyMywiZXhwIjoxNjY1NjU2MDIzfQ.xj-FFOu_9ZjRDZ_zfZ0QwultEPWO1r-0qJmkqTX4d1s
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 954
Host: localhost:8080

{
  "standingOrderIdentification" : {
    "instructionIdentification" : "TEST_STANDING_ORDER_PSD2"
  },
  "amount" : {
    "instructedAmount" : {
      "value" : 10000,
      "currency" : "CZK"
    }
  },
  "requestedExecutionDate" : "2222-09-08",
  "standingOrder" : {
    "alias" : "TEST_STANDING_ORDER_ALIAS",
    "execution" : {
      "mode" : "UNTIL_CANCELLATION",
      "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
      "interval" : "MONTHLY",
      "remitSkipCount" : 1
    }
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ6330300000000000000123"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "Test sprava pro prijemce",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:1000", "KS:2000", "SS:3000" ]
      }
    }
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 37e08f30-ea1f-41e5-bbdb-aa4b4724b395
Content-Length: 318

{
  "standingOrderIdentification" : {
    "transactionIdentification" : "14578"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "DMCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "a8df8a10-a3b0-4639-82ed-235187b3d1a2"
  }
}

Standing order signing

Authorization detail (I)

A GET request to get standing order authorization detail

Path parameters

Table 19. /standingorders/{transactionIdentification}/sign/{signId}
Parameter Description

transactionIdentification

Requested transaction identification

signId

signature id

Response fields

Path Type Description

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED']

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status, e.g. OPEN

signInfo.signId

String

Identifier of the authorization process of a particular transaction.

signInfo.scenario

String

Selected authorization scenario

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /standingorders/14555/sign/d7f113cf-97c5-467b-96eb-47f9e0930452 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:11:48 CEST
X-Request-ID: e3e7deb9-fab5-4eb9-a028-3e1318fe534c
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJlOTBkNzA4Ny0wMzFiLTRhMjMtOTRlNS02MDA3ZmU3ZmQxODUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjMwNSwiZXhwIjoxNjY1NjU1OTA1fQ.fr4WdmEp9JOck6hWP1hvbr2WfY-bfILo1xHA7H6tOxo
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: e3e7deb9-fab5-4eb9-a028-3e1318fe534c
Content-Length: 148

{
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "d7f113cf-97c5-467b-96eb-47f9e0930452"
  }
}

Authorization initiation (II)

A POST request to generate signature

Path parameters

Table 20. /standingorders/{transactionIdentification}/sign/{signId}
Parameter Description

transactionIdentification

Requested transaction identification

signId

signature id

Request parameters

Parameter Description

testAuthCode

if true and application runs in non-production environment, then no SMS is send and auth.code value is always 0000

Request fields

Path Type Description

authorizationType

String

Code of required authorization (from authorization scenarios) - a selected scenario

redirectUrl

String

URL link or package of federated authorization call back address. This address is used by the federated bank authorization to redirect back to the TPP application after authorization is complete

Response fields

Path Type Description

authorizationType

String

Code of required authorization (from authorization scenarios) - a selected scenario

href

Object

Reference to call federated authorization

href.url

String

URL link or package of federated authorization

href.id

String

Possible id for calling federated authorization.

method

String

CMethod to use href link and federated authorization.

code

Object

Structure containing signing data for signing at TPP aplication

code.prefix

String

SMS or Token signing prefix

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status, e.g. OPEN

signInfo.signId

String

Identifier of the authorization process of a particular transaction. Up to 36 chars.

signInfo.scenario

String

Selected authorization scenario

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

POST /standingorders/14555/sign/d7f113cf-97c5-467b-96eb-47f9e0930452?testAuthCode=true HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:11:49 CEST
X-Request-ID: e35a8d7a-dd34-4982-a261-ff5d51bbb568
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJlOTBkNzA4Ny0wMzFiLTRhMjMtOTRlNS02MDA3ZmU3ZmQxODUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjMwNSwiZXhwIjoxNjY1NjU1OTA1fQ.fr4WdmEp9JOck6hWP1hvbr2WfY-bfILo1xHA7H6tOxo
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 37
Host: localhost:8080

{
  "authorizationType" : "SMS_TPP"
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: e35a8d7a-dd34-4982-a261-ff5d51bbb568
Content-Length: 212

{
  "authorizationType" : "SMS_TPP",
  "code" : {
    "prefix" : "EPC"
  },
  "signInfo" : {
    "state" : "CODE_GENERATED",
    "signId" : "d7f113cf-97c5-467b-96eb-47f9e0930452",
    "scenario" : "SMS_TPP"
  }
}

Authorization initiation (III)

A PUT request to confirm signature

Path parameters

Table 21. /standingorders/{transactionIdentification}/sign/{signId}
Parameter Description

transactionIdentification

Requested transaction identification

signId

signature id

Request fields

Path Type Description

code

Object

Structure of authorization code

code.code

String

authorization code value - one time password (SMS signing code, Token signing code)

Response fields

Path Type Description

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status, e.g. OPEN

signInfo.signId

String

Identifier of the authorization process of a particular transaction. Up to 36 chars.

signInfo.scenario

String

Selected authorization scenario

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

PUT /standingorders/14555/sign/d7f113cf-97c5-467b-96eb-47f9e0930452 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:11:50 CEST
X-Request-ID: 83fd3801-d379-4185-b1b8-6a3f9920ec5a
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJlOTBkNzA4Ny0wMzFiLTRhMjMtOTRlNS02MDA3ZmU3ZmQxODUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjMwNSwiZXhwIjoxNjY1NjU1OTA1fQ.fr4WdmEp9JOck6hWP1hvbr2WfY-bfILo1xHA7H6tOxo
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 40
Host: localhost:8080

{
  "code" : {
    "code" : "0000"
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 83fd3801-d379-4185-b1b8-6a3f9920ec5a
Content-Length: 133

{
  "signInfo" : {
    "state" : "COMPLETED",
    "signId" : "d7f113cf-97c5-467b-96eb-47f9e0930452",
    "scenario" : "SMS_TPP"
  }
}

New Batch payment

A POST request to enter a batch payment.

Additional information

  • the number of payments in a batch payment is not limited

  • batch payment can include domestic and foreign payments together

Request fields

Path Type Description

exchangeIdentification

String

Required. Max18Text Clear query identification

instructionName

String

Max35Text An entry field for an optional batch name

payments

Array

Required. Max18Text Clear query identification

payments[].signId

String

Required. Max35Text Identifier of the authorization process of a particular transaction

Response fields

Path Type Description

transactionIdentification

String

Max35Text An entry field for an optional batch name

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED']

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status

signInfo.signId

String

Max35Text Identifier of the authorization process of a particular transaction

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Batch payment

Request

POST /batchpayments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:08:02 CEST
X-Request-ID: 25d12a97-6753-4674-8f0d-c0efd22930eb
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIzY2VlYzYwYi00NDRmLTQ3MDQtOWQwYi1kNjJiNmM1MDQzMGYiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjA4MCwiZXhwIjoxNjY1NjU1NjgwfQ.VI7GkWiLUF1W9MRfLnVKfQKxpulTprDd0McF1Z4zSzQ
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 297
Host: localhost:8080

{
  "exchangeIdentification" : "658576010faf0a23dc",
  "instructionName" : "TestBatchPayment",
  "payments" : [ {
    "signId" : "95e9cd0a-4de8-4453-b7ce-0f04967b5e11"
  }, {
    "signId" : "6d63e4df-11e5-4752-baba-2bfb49fdb018"
  }, {
    "signId" : "f4ca712c-ed71-4377-84bb-f8ded713f6ad"
  } ]
}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 25d12a97-6753-4674-8f0d-c0efd22930eb
Content-Length: 220

{
  "transactionIdentification" : "6a804bf1-9538-47bf-af2b-bf11f51b562c",
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "b98f87f9-fad4-45ec-b08f-ea8306307be9"
  }
}

Batch payment with not existing payment sign id

Request

POST /batchpayments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:06:49 CEST
X-Request-ID: 5c920474-137d-4dd1-96a9-0e5f2aa98528
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhZWY4MzI1Ny0zNjUwLTQ5ZjMtYjRkMS1mZTJlZmE0OTlkN2UiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjAwNywiZXhwIjoxNjY1NjU1NjA3fQ.YD4Sj4CFFCxi2aY0i91YUl4TJ1DreTD3yeGftPvHAyQ
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 341
Host: localhost:8080

{
  "exchangeIdentification" : "658576010faf0a23dc",
  "instructionName" : "TestBatchPayment",
  "payments" : [ {
    "signId" : "75329b32-cb6e-4d8e-80d1-99ab495fe96d"
  }, {
    "signId" : "b1e0df0e-4827-4d71-b699-857c17e13d62"
  }, {
    "signId" : "5b126e8b-2f06-49f2-b9e3-a69a6eb6289f"
  }, {
    "signId" : "NotExisting-ID-0000"
  } ]
}

Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
X-Request-ID: 5c920474-137d-4dd1-96a9-0e5f2aa98528
Content-Type: application/json;charset=UTF-8
Content-Length: 134

{
  "errors" : [ {
    "error" : "INCORRECT_SIGNID",
    "scope" : "payments.signId",
    "message" : "Payment does not exist"
  } ]
}

Batch payment status

A GET request to get batch payment status.

Differences from COBS standard

  • extra field “instructionStatus” for individual payments is returned in response

Path parameters

Table 22. /batchpayments/{transactionIdentification}/status
Parameter Description

transactionIdentification

Requested transaction identification

Response fields

Path Type Description

instructionStatus

String

Status of entered batch payment

payments

Array

Max18Text Clear query identification

payments[].transactionIdentification

String

Max35Text Identifier of established individual transaction

payments[].instructionStatus

String

Status of payment

payments[].signInfo

Object

Status information and id of unauthorized transactions

payments[].signInfo.state

String

Transaction authorization status

payments[].signInfo.signId

String

Max35Text Identifier of the authorization process of a particular transaction

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /batchpayments/ff255a85-47db-4952-a384-a88134dad3c8/status HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:08:57 CEST
X-Request-ID: ef096e53-4d72-4772-8913-e2a125275b72
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIzYzY2M2E2Mi03MTIyLTQ0MzYtYmZhYi0xZDNjN2ZlMWViYWMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjEzNSwiZXhwIjoxNjY1NjU1NzM1fQ.UK2dkyzuoghU1-5TkpimyCeAZl38L2jYGSe7EDBqiCU
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: ef096e53-4d72-4772-8913-e2a125275b72
Content-Length: 644

{
  "instructionStatus" : "ACTC",
  "payments" : [ {
    "transactionIdentification" : "TPSD004569392",
    "instructionStatus" : "ACTC",
    "signInfo" : {
      "state" : "OPEN",
      "signId" : "ea16a1e1-ea7c-4180-8933-4fcd0a7497c0"
    }
  }, {
    "transactionIdentification" : "TPSD004569392",
    "instructionStatus" : "ACTC",
    "signInfo" : {
      "state" : "OPEN",
      "signId" : "5e87cfc1-908b-4657-867b-190c0edf126a"
    }
  }, {
    "transactionIdentification" : "TPSD004569392",
    "instructionStatus" : "ACTC",
    "signInfo" : {
      "state" : "OPEN",
      "signId" : "b4130a18-1992-4006-b68b-c8248ffed5b8"
    }
  } ]
}

Batch payment delete

A DELETE request to delete standing order

Path parameters

Table 23. /batchpayments/{transactionIdentification}
Parameter Description

transactionIdentification

Required. Requested transaction identification

Request parameters

Parameter Description

allInstructions

If this parameter is set to true, it is required to delete this bulk payment, but also all individual bulk instructions

Example

DELETE /batchpayments/f7ed8412-0373-44f1-b1b9-0236061c8dcd HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:08:28 CEST
X-Request-ID: a7069b9d-6649-47f0-87be-2cdef204cc50
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJmYTUxOTM1NC0zNzI0LTRhNTctODQ0NS0yNzA2Njk5ZTRkMjMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjEwNywiZXhwIjoxNjY1NjU1NzA3fQ.X_Il-UQuzcGv4vU3Cjz44hLMkgvrVfMrgeE6fpXtY6c
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: a7069b9d-6649-47f0-87be-2cdef204cc50

Example of deleting with instructions

DELETE /batchpayments/00f9ad9f-0041-4002-b36a-c8245db30637?allInstructions=true HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:07:13 CEST
X-Request-ID: a8002967-7cf1-4e5c-82f9-fa6c29a5ee7a
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhNTIyOWE5NS1mNDBlLTQyYjMtYWMwMi1mM2ZkMmVhMjk3YzYiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjAzMSwiZXhwIjoxNjY1NjU1NjMxfQ.2QU82e2jYeAiUDAOsAJ7kKV850Qq_fPrw18N22uhdog
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: a8002967-7cf1-4e5c-82f9-fa6c29a5ee7a

Batch payment signing

Authorization detail (I)

A GET request to get batch payment authorization detail

Path parameters

Table 24. /batchpayments/{transactionIdentification}/sign/{signId}
Parameter Description

transactionIdentification

Required. Requested transaction identification

signId

Required. Requested signature id

Response fields

Path Type Description

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED']

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status, e.g. OPEN

signInfo.signId

String

Identifier of the authorization process of a particular transaction.

signInfo.scenario

String

Selected authorization scenario

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

GET /batchpayments/df210c5b-4bf4-4abe-b63b-b84c096b2e65/sign/3e71638e-059d-4acb-bcc8-f53d79071ab1 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:07:38 CEST
X-Request-ID: fd65a5b6-c32a-45a8-8196-f727a3f82674
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJjOWMwNjA0Mi0xMmM0LTQ1ZWMtYmE2ZC1iY2NhZGMwM2ZkYmYiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjA1NiwiZXhwIjoxNjY1NjU1NjU2fQ.64ARytkzjeOmXedTaEHevs_pZwm6e2qW9W_mF_ZiduA
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: fd65a5b6-c32a-45a8-8196-f727a3f82674
Content-Length: 148

{
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "3e71638e-059d-4acb-bcc8-f53d79071ab1"
  }
}

Authorization initiation (II)

A POST request to generate signature

Path parameters

Table 25. /batchpayments/{transactionIdentification}/sign/{signId}
Parameter Description

transactionIdentification

Required. Requested transaction identification

signId

Required. Requested signature id

Request parameters

Parameter Description

testAuthCode

if true and application runs in non-production environment, then no SMS is send and auth.code value is always 0000

Request fields

Path Type Description

authorizationType

String

Code of required authorization (from authorization scenarios) - a selected scenario

redirectUrl

String

URL link or package of federated authorization call back address. This address is used by the federated bank authorization to redirect back to the TPP application after authorization is complete

Response fields

Path Type Description

authorizationType

String

Code of required authorization (from authorization scenarios) - a selected scenario

href

Object

Reference to call federated authorization

href.url

String

URL link or package of federated authorization

href.id

String

Possible id for calling federated authorization.

method

String

CMethod to use href link and federated authorization.

code

Object

Structure containing signing data for signing at TPP aplication

code.prefix

String

SMS or Token signing prefix

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status, e.g. OPEN

signInfo.signId

String

Identifier of the authorization process of a particular transaction. Up to 36 chars.

signInfo.scenario

String

Selected authorization scenario

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

POST /batchpayments/df210c5b-4bf4-4abe-b63b-b84c096b2e65/sign/3e71638e-059d-4acb-bcc8-f53d79071ab1?testAuthCode=true HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:07:39 CEST
X-Request-ID: 2b9e7737-7dac-404a-b3af-d66b84787d0b
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJjOWMwNjA0Mi0xMmM0LTQ1ZWMtYmE2ZC1iY2NhZGMwM2ZkYmYiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjA1NiwiZXhwIjoxNjY1NjU1NjU2fQ.64ARytkzjeOmXedTaEHevs_pZwm6e2qW9W_mF_ZiduA
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 37
Host: localhost:8080

{
  "authorizationType" : "SMS_TPP"
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 2b9e7737-7dac-404a-b3af-d66b84787d0b
Content-Length: 212

{
  "authorizationType" : "SMS_TPP",
  "code" : {
    "prefix" : "BMA"
  },
  "signInfo" : {
    "state" : "CODE_GENERATED",
    "signId" : "3e71638e-059d-4acb-bcc8-f53d79071ab1",
    "scenario" : "SMS_TPP"
  }
}

Authorization initiation (III)

A PUT request to confirm signature

Path parameters

Table 26. /batchpayments/{transactionIdentification}/sign/{signId}
Parameter Description

transactionIdentification

Required. Requested transaction identification

signId

Required. Requested signature id

Request fields

Path Type Description

code

Object

Structure of authorization code

code.code

String

authorization code value - one time password (SMS signing code, Token signing code)

Response fields

Path Type Description

signInfo

Object

Status information and id of unauthorized transactions

signInfo.state

String

Transaction authorization status, e.g. OPEN

signInfo.signId

String

Identifier of the authorization process of a particular transaction. Up to 36 chars.

signInfo.scenario

String

Selected authorization scenario

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example

PUT /batchpayments/df210c5b-4bf4-4abe-b63b-b84c096b2e65/sign/3e71638e-059d-4acb-bcc8-f53d79071ab1 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:07:41 CEST
X-Request-ID: aef69209-bd73-4fc0-87bd-767b67574264
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJjOWMwNjA0Mi0xMmM0LTQ1ZWMtYmE2ZC1iY2NhZGMwM2ZkYmYiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTY2NTY1MjA1NiwiZXhwIjoxNjY1NjU1NjU2fQ.64ARytkzjeOmXedTaEHevs_pZwm6e2qW9W_mF_ZiduA
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 40
Host: localhost:8080

{
  "code" : {
    "code" : "0000"
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: aef69209-bd73-4fc0-87bd-767b67574264
Content-Length: 133

{
  "signInfo" : {
    "state" : "COMPLETED",
    "signId" : "3e71638e-059d-4acb-bcc8-f53d79071ab1",
    "scenario" : "SMS_TPP"
  }
}

CISP API

Balance check (CISP)

A POST request to balance check. User token is not required

Request fields

Path Type Description

exchangeIdentification

String

Max35Text Clear query identification, required

card.cardholderName

String

Max45Text Card holder name, optional

card.maskedPan

String

Max30Text Masked card number, optional

debtorAccount.identification.iban

String

IBAN2007Identifier Account number for charges in IBAN format

debtorAccount.currency

String

CurrencyCode, ISO 4217 Payer account currency, optional

authenticationMethod

String

Client verification method, see AuthenticationMethod enum in COBS for possible values, optional

merchant.identification

String

Merchant identification, optional

merchant.type

String

Merchant type, see COBS enum for possible values, optional

merchant.shortName

String

Max35Text Merchant name, optional

merchant.commonName

String

Max70Text Merchant name as stated in the payment receipt, optional

merchant.address

String

Max140Text Merchant address, optional

merchant.countryCode

String

CountryCode, ISO 3166 (2 alphanumeric characters code version) Merchant country, optional

merchant.merchantCategoryCode

String

Min3Max4Text, ISO 18245, Merchant code following the transaction type, optional

transactionDetails.totalAmount

Number

Balance query amount

transactionDetails.currency

String

Balance query currency

Response fields

Path Type Description

responseIdentification

Number

Unique identification of response to query, number

exchangeIdentification

String

Max35Text Clear query identification from request

response

String

APPR - approved, DECL - declined

errors[]

Array

List of errors

errors[].error

String

Error code as defined by COBS

errors[].parameters

Object

Error parameters

errors[].scope

String

Error scope

errors[].message

String

Error detailed message (free text)

Example #1 - error, bad IBAN

POST /accounts/balanceCheck HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:50 CEST
X-Request-ID: 36667040-c8a9-4167-abd8-6401b9384dff
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 619
Host: localhost:8080

{
  "exchangeIdentification" : "BC1665652250837",
  "card" : {
    "cardholderName" : "Jan Zelenka",
    "maskedPan" : "1234********6789"
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZSPATNYIBAN"
    },
    "currency" : "CZK"
  },
  "authenticationMethod" : "NPIN",
  "merchant" : {
    "identification" : "471 16 129",
    "type" : "MERC",
    "shortName" : "NEOLUXOR",
    "commonName" : "Neoluxor s.r.o.",
    "address" : "Hlavní 5, Praha 1",
    "countryCode" : "CZ",
    "merchantCategoryCode" : "5192"
  },
  "transactionDetails" : {
    "currency" : "CZK",
    "totalAmount" : 1000
  }
}
HTTP/1.1 400 Bad Request
Cache-Control: no-store
X-Request-ID: 36667040-c8a9-4167-abd8-6401b9384dff
Content-Type: application/json;charset=UTF-8
Content-Length: 132

{
  "errors" : [ {
    "error" : "AC02",
    "scope" : "debtorAccount.identification.iban",
    "message" : "IBAN not valid"
  } ]
}

Example #2 - ok, declined, insufficient amount

POST /accounts/balanceCheck HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:50 CEST
X-Request-ID: 919f5d81-897f-4a79-8eb4-88746ff22aa2
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 634
Host: localhost:8080

{
  "exchangeIdentification" : "BC1665652250883",
  "card" : {
    "cardholderName" : "Jan Zelenka",
    "maskedPan" : "1234********6789"
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "authenticationMethod" : "NPIN",
  "merchant" : {
    "identification" : "471 16 129",
    "type" : "MERC",
    "shortName" : "NEOLUXOR",
    "commonName" : "Neoluxor s.r.o.",
    "address" : "Hlavní 5, Praha 1",
    "countryCode" : "CZ",
    "merchantCategoryCode" : "5192"
  },
  "transactionDetails" : {
    "currency" : "EUR",
    "totalAmount" : 1000000
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 919f5d81-897f-4a79-8eb4-88746ff22aa2
Content-Length: 117

{
  "exchangeIdentification" : "BC1665652250883",
  "responseIdentification" : 1665652250967,
  "response" : "DECL"
}

Example #3 - ok, approved

POST /accounts/balanceCheck HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json; charset=utf-8
Accept-Language: cs
Date: Thu, 13 Oct 2022 11:10:51 CEST
X-Request-ID: 5a5a59ee-9587-4842-9b57-0c5d596feb9a
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Content-Length: 628
Host: localhost:8080

{
  "exchangeIdentification" : "BC1665652251018",
  "card" : {
    "cardholderName" : "Jan Zelenka",
    "maskedPan" : "1234********6789"
  },
  "debtorAccount" : {
    "identification" : {
      "iban" : "CZ2140000000007255060007"
    },
    "currency" : "CZK"
  },
  "authenticationMethod" : "NPIN",
  "merchant" : {
    "identification" : "471 16 129",
    "type" : "MERC",
    "shortName" : "NEOLUXOR",
    "commonName" : "Neoluxor s.r.o.",
    "address" : "Hlavní 5, Praha 1",
    "countryCode" : "CZ",
    "merchantCategoryCode" : "5192"
  },
  "transactionDetails" : {
    "currency" : "CZK",
    "totalAmount" : 1
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 5a5a59ee-9587-4842-9b57-0c5d596feb9a
Content-Length: 117

{
  "exchangeIdentification" : "BC1665652251018",
  "responseIdentification" : 1665652251073,
  "response" : "APPR"
}