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@expobank.cz.

Not yet implemented

  • standing orders

  • batch payments

  • 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 /api/oauth2/register HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Language: cs
Host: localhost:8080
Content-Length: 258

{
  "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
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" : "1ca773b4-26de-4c48-8a42-3286db428ad4",
  "client_secret" : "qNvgFocwcUQMVGnVJsKFU8dV3NZV5EKcazszHzr4jybL4kDe02H2hJo32NdkU928",
  "client_secret_expires_at" : 0,
  "api_key" : "qPZoazrKe7HBpX8NUVf6j5Lt7zwcjZrshyuZP0Q2syTx1CNnl5NcXKxwNx9WkFAL",
  "client_name#en-US" : "TEST TPP english name"
}

TPP registered data

A GET request to get TPP registered info

Path parameters

Table 1. /api/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 /api/oauth2/register/1ca773b4-26de-4c48-8a42-3286db428ad4 HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
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" : "1ca773b4-26de-4c48-8a42-3286db428ad4",
  "client_secret" : "qNvgFocwcUQMVGnVJsKFU8dV3NZV5EKcazszHzr4jybL4kDe02H2hJo32NdkU928",
  "client_secret_expires_at" : 0,
  "api_key" : "qPZoazrKe7HBpX8NUVf6j5Lt7zwcjZrshyuZP0Q2syTx1CNnl5NcXKxwNx9WkFAL",
  "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. /api/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 /api/oauth2/register/1ca773b4-26de-4c48-8a42-3286db428ad4 HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Language: cs
Host: localhost:8080
Content-Length: 266

{
  "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
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" : "1ca773b4-26de-4c48-8a42-3286db428ad4",
  "client_name#en-US" : "TEST TPP english name 2."
}

Delete registered TPP

A DELETE request to delete registered TPP

Path parameters

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

client_id

client_id

Example

DELETE /api/oauth2/register/1ca773b4-26de-4c48-8a42-3286db428ad4 HTTP/1.1
Content-Type: application/json
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. /api/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 /api/oauth2/register/1ca773b4-26de-4c48-8a42-3286db428ad4/renewSecret HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
Content-Length: 180

{
  "client_id" : "1ca773b4-26de-4c48-8a42-3286db428ad4",
  "client_secret" : "hiNxTeIxZoUWrsOLEDKemin3aSTAUoEQXuPT0GGccV6p4P26GFXVtXrHFlIHbxUB",
  "client_secret_expires_at" : 0
}

Renew API key

A POST request to renew API key on registered TPP

Path parameters

Table 5. /api/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 /api/oauth2/register/1ca773b4-26de-4c48-8a42-3286db428ad4/renewKey HTTP/1.1
Content-Type: application/json
X-ClientCert: -----BEGIN CERTIFICATE-----
MIIIITCCBgmgAwIBAgIJAgWpniLX8ktgMA0GCSqGSIb3DQEBCwUAMH8xCzAJBgNV
BAYTAkNaMSgwJgYDVQQDDB9JLkNBIFRFU1QgU1NMIEVWIENBL1JTQSAxMC8yMDE3
MS0wKwYDVQQKDCRQcnZuw60gY2VydGlmaWthxI1uw60gYXV0b3JpdGEsIGEucy4x
FzAVBgNVBGEMDk5UUkNaLTI2NDM5Mzk1MB4XDTE5MDYyNzA2NTAyNFoXDTIwMDYy
NjA2NTAyNFowgfsxCzAJBgNVBAYTAkNaMRQwEgYDVQQDDAtleHBvYmFuay5jejEZ
MBcGA1UECgwQRXhwb2JhbmsgQ1ogYS5zLjEaMBgGA1UECQwRTmEgU3Ryxb5pIDIw
OTcvNjMxEDAOBgNVBAcMB1ByYWhhIDQxDjAMBgNVBBEMBTE0MDAwMREwDwYDVQQF
EwgxNDg5MzY0OTEdMBsGA1UEDwwUUHJpdmF0ZSBPcmdhbml6YXRpb24xEzARBgsr
BgEEAYI3PAIBAxMCQ1oxHTAbBgNVBAgMFEhsYXZuw60gbcSbc3RvIFByYWhhMRcw
FQYDVQRhDA5OVFJDWi0xNDg5MzY0OTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBALrzMwOBqnVhy0/+j5LNp2gKPgDdoUZGhzVK0TEy0xcRwY2PGOby7ibK
rauFbQHG/mFFTfoQBKMYiftxPXZDhRYh+9Moiuv6hpuJg3YGcg/uROQxoyDoDNxj
oLGn+Aa+xBoqjWnz6ttkEcYzDjfcnjowWqdtDrrwBb1URaGauMRgfHtmm019ECVJ
GK3ZhuyADDTSqK87fSlqy1LzZbdHmDe18+PqQIEtkOn/C7QQhdnIzWPDDmRJmrFh
HtRNLUZAkq+GJdYCmyah09beHzWJUxzVIUYlji4C2sjexuKnrc8/AL99qAefi8U3
Wk8d9xZCHLMejYKX8e42ReKJgviyo1sCAwEAAaOCAyEwggMdMBYGA1UdEQQPMA2C
C2V4cG9iYW5rLmN6MAkGA1UdEwQCMAAwgeYGA1UdIASB3jCB2zCBzQYNKwYBBAGB
uEgKAygBATCBuzAdBggrBgEFBQcCARYRaHR0cDovL3d3dy5pY2EuY3owgZkGCCsG
AQUFBwICMIGMGoGJVGVudG8gVEVTVCBjZXJ0aWZpa2F0IGJ5bCB2eWRhbiB2IHNv
dWxhZHUgcyBuYXJpemVuaW0gRVUgYy4gbm5uL1JSUlQuVGhpcyBpcyBhIFRFU1Qg
Y2VydGlmaWNhdGUgYWNjb3JkaW5nIHRvIFJlZ3VsYXRpb24gKEVVKSBObyBubm4v
UlJSUi4wCQYHBACL7EABBDAzBgNVHR8ELDAqMCigJqAkhiJodHRwOi8vdGVzdHEu
aWNhLmN6L3RxY3cxN19yc2EuY3JsMGoGCCsGAQUFBwEBBF4wXDAuBggrBgEFBQcw
AoYiaHR0cDovL3Rlc3RxLmljYS5jei90cWN3MTdfcnNhLmNlcjAqBggrBgEFBQcw
AYYeaHR0cDovL3RvY3NwLmljYS5jei90cWN3MTdfcnNhMA4GA1UdDwEB/wQEAwIF
oDCB/gYIKwYBBQUHAQMEgfEwge4wCAYGBACORgEBMBMGBgQAjkYBBjAJBgcEAI5G
AQYDMFYGBgQAjkYBBTBMMCQWHmh0dHA6Ly90ZXN0cS5pY2EuY3ovcGRzX2NzLnBk
ZhMCY3MwJBYeaHR0cDovL3Rlc3RxLmljYS5jei9wZHNfZW4ucGRmEwJlbjB1BgYE
AIGYJwIwazBMMBEGBwQAgZgnAQEMBlBTUF9BUzARBgcEAIGYJwECDAZQU1BfUEkw
EQYHBACBmCcBAwwGUFNQX0FJMBEGBwQAgZgnAQQMBlBTUF9JQwwTQ3plY2ggTmF0
aW9uYWwgQmFuawwGQ1otQ05CMB8GA1UdIwQYMBaAFDr/54EnzNLKJxnnGqHQGjvG
sJ+qMB0GA1UdDgQWBBS9yz/0MZk4SYWKxnLjqzRCEKmmaDAdBgNVHSUEFjAUBggr
BgEFBQcDAQYIKwYBBQUHAwIwDQYJKoZIhvcNAQELBQADggIBADPWstwIf1lbo5ic
Zh+XmvCdIzRhrpuLT3DgypMKIAOz6kF5yPx9lWaYFpXWfubmJBiH9BF8gKnsrGss
LM7Z5AV38hvY8Mj5L5Ssl7XGrk6UcKTm1DB/Y4yIEvDcC0DSTdzQn++3M9uE/wc9
4kZzxFXICyaMVrIBnNrZvOvShDGVEFWPy7VSAs7ntx1o/gF3aFB/xjr0AGizzkA/
yUwoPwn0MHc26m9vPppJCmLa671jHhbzGFsZBUO0tf8J9fvwKKRYC6dxz74TYHPV
Y3sYgrHoO20J3B59mfrb31gXJXIMBuYLVHyfitH9mf0U+Gp7/tPgmt7GiAOTcEPa
nyZUofAs1kbmhltl5nu+hcTVzu6DcqD12rLivDvILTXTWbyOJ1x0fw13UxchnhTx
MmDnOxVIrD56G+MV/+bPAoORnk5KFVvRrs5fL/6hQ13rU/XCgSa/uo5swp825lsU
XZpyGfXBifLEBivbQuUKxx6hiPKFhRtZ/bkd0lLq5QMdz4wWhXtfln8ZeqyMtGyO
T1LSs78Cv7goPsgRQJMpGvyX5j/GdK8rNyTzhh9Yg9qy/2EOvAEXb+Q6m3zbctgt
SjJ6+UJ8xcMVAwkG4iugnWvJQyefy7gXMsYoz4tEckywmNCbTA7Qrl7LW+fL4qvw
wBoCnUF/b1rfMYtn4675VoTvXsUA
-----END CERTIFICATE-----
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
Content-Length: 140

{
  "client_id" : "1ca773b4-26de-4c48-8a42-3286db428ad4",
  "api_key" : "N0nq5zoot0ZsAz1LVLeYpqnO1iYvgqsHLGmv1izxMCYsvdLTmROU6iomsWhrmv5h"
}

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 /api/oauth2/auth?response_type=code&redirect_uri=https%3A%2F%2Ftpp.cz&client_id=1ca773b4-26de-4c48-8a42-3286db428ad4&scope=aisp&state=nejaky_state HTTP/1.1
Content-Type: application/json
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 302 Found
Cache-Control: no-store
Location: https://tpp.cz?error=unauthorized_client&state=nejaky_state&error_description=TPP%20client_id%20is%20not%20authorized

OK Example

GET /api/oauth2/auth?response_type=code&redirect_uri=https%3A%2F%2Ftpp.cz&client_id=1ca773b4-26de-4c48-8a42-3286db428ad4&scope=aisp&state=nejaky_state HTTP/1.1
Content-Type: application/json
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 /api/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Accept-Language: cs
Host: localhost:8080

grant_type=authorization_code&code=GY2WDM1LMVLUZ92L46LC9AIQA3Z1CLU2TZQCKL7DCIPY5RKAEJKBXC5M9YWGBGGB&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
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
Content-Length: 968

{
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJmZTQyODRmYy03OTM4LTQzNTktYWZhYS05MjZmNjMzYTg5NWMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzg4NSwiZXhwIjoxNTk0NzI3NDg1fQ.bBI33BE6B74hnblraRCo1a8wqfIcYocOTs21c-8Z7hk",
  "refresh_token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiMzNjYzhiZC03MDY3LTQwNzktODlkYi03NGU1MDA5YzFlNDUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzg4NSwiZXhwIjoxNjAyNDk5ODg1fQ.XHEkk2__1uD7AAkb88D02QLOotfUmDb3oGlRvwhueLc",
  "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 /api/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Accept-Language: cs
Host: localhost:8080

grant_type=refresh_token&client_id=1ca773b4-26de-4c48-8a42-3286db428ad4&refresh_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6IjBkNGNjYzRmLTVhOGYtNGZjNC05NjcwLTI3Y2NhYjU1MWE4OSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiIxY2E3NzNiNC0yNmRlLTRjNDgtOGE0Mi0zMjg2ZGI0MjhhZDQiLCJzY29wZXMiOlsicGlzcCIsImFpc3AiXSwiaWF0IjoxNTk0NzIzNjY3LCJleHAiOjE2MDI0OTk2Njd9.D763U6qk_ETEwgh87iLgi6AnMV0G88eX0XE74EOdhGw
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
Content-Length: 495

{
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6IjY0NTM1Yjc3LTMzZDMtNGZlMC04YmVlLWZhNGYzZDE2NzE3NSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiIxY2E3NzNiNC0yNmRlLTRjNDgtOGE0Mi0zMjg2ZGI0MjhhZDQiLCJzY29wZXMiOlsicGlzcCIsImFpc3AiXSwiaWF0IjoxNTk0NzIzNjcwLCJleHAiOjE1OTQ3MjcyNzB9.pJ3h18ps0MZZ2Uwec3c0kpdXGpKzJ-1XtBIFAa11frU",
  "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 /api/oauth2/revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Accept-Language: cs
Host: localhost:8080

token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6IjBkNGNjYzRmLTVhOGYtNGZjNC05NjcwLTI3Y2NhYjU1MWE4OSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiIxY2E3NzNiNC0yNmRlLTRjNDgtOGE0Mi0zMjg2ZGI0MjhhZDQiLCJzY29wZXMiOlsicGlzcCIsImFpc3AiXSwiaWF0IjoxNTk0NzIzNjY3LCJleHAiOjE2MDI0OTk2Njd9.D763U6qk_ETEwgh87iLgi6AnMV0G88eX0XE74EOdhGw
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

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 /api/accounts HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:46:42 CEST
X-Request-ID: 425cc35a-6f7b-4173-98df-4a764f88a6cc
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwYmNlYjhkMC1kZDc3LTRlYTUtODJlMS1iY2VjNjlmNDVhZjUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYwMCwiZXhwIjoxNTk0NzI3MjAwfQ.uekOMJH45t5FQUoPRa-4worigRTucZf7bs22ngNTxAg
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: 425cc35a-6f7b-4173-98df-4a764f88a6cc
Content-Length: 1605

{
  "pageNumber" : 0,
  "pageCount" : 1,
  "totalCount" : 4,
  "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" : "350C80CE-FF31-46C3-8378-E33D7D5C541D",
    "identification" : {
      "iban" : "CZ5240000000007255060031",
      "other" : "7255060031"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Expo Global",
    "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 /api/accounts?sort=currency&order=asc HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:46:43 CEST
X-Request-ID: 7d67d05a-0d37-46c6-bb93-75b2e7fc413d
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwYmNlYjhkMC1kZDc3LTRlYTUtODJlMS1iY2VjNjlmNDVhZjUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYwMCwiZXhwIjoxNTk0NzI3MjAwfQ.uekOMJH45t5FQUoPRa-4worigRTucZf7bs22ngNTxAg
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: 7d67d05a-0d37-46c6-bb93-75b2e7fc413d
Content-Length: 1605

{
  "pageNumber" : 0,
  "pageCount" : 1,
  "totalCount" : 4,
  "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" : "350C80CE-FF31-46C3-8378-E33D7D5C541D",
    "identification" : {
      "iban" : "CZ5240000000007255060031",
      "other" : "7255060031"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Expo Global",
    "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 /api/accounts?sort=currency%2Cidentification.other&order=desc%2Casc HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:46:44 CEST
X-Request-ID: 5eed9c43-2ad3-4f52-b792-f82855b6d8ea
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwYmNlYjhkMC1kZDc3LTRlYTUtODJlMS1iY2VjNjlmNDVhZjUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYwMCwiZXhwIjoxNTk0NzI3MjAwfQ.uekOMJH45t5FQUoPRa-4worigRTucZf7bs22ngNTxAg
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: 5eed9c43-2ad3-4f52-b792-f82855b6d8ea
Content-Length: 1605

{
  "pageNumber" : 0,
  "pageCount" : 1,
  "totalCount" : 4,
  "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" ]
  }, {
    "id" : "350C80CE-FF31-46C3-8378-E33D7D5C541D",
    "identification" : {
      "iban" : "CZ5240000000007255060031",
      "other" : "7255060031"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Expo Global",
    "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 6. /api/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 /api/accounts/339382F0-2608-4E08-B9A6-4A28D1960790/balance HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:46:48 CEST
X-Request-ID: 3e2c1944-4749-462b-9538-a2e1ba5a43aa
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwYmNlYjhkMC1kZDc3LTRlYTUtODJlMS1iY2VjNjlmNDVhZjUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYwMCwiZXhwIjoxNTk0NzI3MjAwfQ.uekOMJH45t5FQUoPRa-4worigRTucZf7bs22ngNTxAg
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: 3e2c1944-4749-462b-9538-a2e1ba5a43aa
Content-Length: 860

{
  "balances" : [ {
    "type" : {
      "codeOrProprietary" : {
        "code" : "TOTAL_AVAILABLE_BALANCE"
      }
    },
    "amount" : {
      "value" : 4.63,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "CRDT",
    "date" : {
      "dateTime" : "2020-07-14T10:46:48.468Z"
    }
  }, {
    "type" : {
      "codeOrProprietary" : {
        "code" : "CURRENT_BALANCE"
      }
    },
    "amount" : {
      "value" : 4.63,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "CRDT",
    "date" : {
      "dateTime" : "2020-07-14T10:46:48.468Z"
    }
  }, {
    "type" : {
      "codeOrProprietary" : {
        "code" : "OPENING_BALANCE"
      }
    },
    "amount" : {
      "value" : 4.63,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "CRDT",
    "date" : {
      "dateTime" : "2020-07-13T22: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,

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

Path parameters

Table 7. /api/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 /api/accounts/339382F0-2608-4E08-B9A6-4A28D1960790/transactions?fromDate=2020-01-14&page=0&size=10 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:46:35 CEST
X-Request-ID: 89327408-df16-4b53-9455-256a543188cb
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI0ZTg1ZDYwYi1iMjVmLTQ4ZGEtOGVjYi04OTYxM2E1OGEyN2YiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzU5MywiZXhwIjoxNTk0NzI3MTkzfQ.la_CB8K3vumaSusT5K-X5r5hPonlHg1DluwYboJ9JZU
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: 89327408-df16-4b53-9455-256a543188cb
Content-Length: 22042

{
  "pageNumber" : 0,
  "nextPage" : 1,
  "pageSize" : 10,
  "transactions" : [ {
    "entryReference" : "001D11F201910002-TIBD004873024",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-07-09"
    },
    "valueDate" : {
      "date" : "2020-07-09"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004873024",
          "accountServicerReference" : "001D11F201910002",
          "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" : "001D11F201890009-TIBD004872778",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-07-07"
    },
    "valueDate" : {
      "date" : "2020-07-07"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004872778",
          "accountServicerReference" : "001D11F201890009",
          "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" : "001D11F201890003-TIBD004872770",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-07-07"
    },
    "valueDate" : {
      "date" : "2020-07-07"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004872770",
          "accountServicerReference" : "001D11F201890003",
          "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" : "001D11E201840002-TIBD004872705",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-07-02"
    },
    "valueDate" : {
      "date" : "2020-07-02"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004872705",
          "accountServicerReference" : "001D11E201840002",
          "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" : "001D11E201840001-TIBD004872702",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-07-02"
    },
    "valueDate" : {
      "date" : "2020-07-02"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004872702",
          "accountServicerReference" : "001D11E201840001",
          "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" : "001D11F201840002-TIBD004872691",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-07-02"
    },
    "valueDate" : {
      "date" : "2020-07-02"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004872691",
          "accountServicerReference" : "001D11F201840002",
          "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" : "001D11E201830001-TIBD004872581",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-07-01"
    },
    "valueDate" : {
      "date" : "2020-07-01"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004872581",
          "accountServicerReference" : "001D11E201830001",
          "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" : "001D11E201810002-TIBD004872532",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-06-29"
    },
    "valueDate" : {
      "date" : "2020-06-29"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004872532",
          "accountServicerReference" : "001D11E201810002",
          "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" : "001D11F201770002-TIBD004872014",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-06-25"
    },
    "valueDate" : {
      "date" : "2020-06-25"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004872014",
          "accountServicerReference" : "001D11F201770002",
          "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" : "001D11E201760002-TIBD004871952",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2020-06-24"
    },
    "valueDate" : {
      "date" : "2020-06-24"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004871952",
          "accountServicerReference" : "001D11E201760002",
          "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 /api/standingorders?page=0&size=2 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:46:55 CEST
X-Request-ID: 42d875d2-0281-4203-a9a7-7ad5a3729f36
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI0MGFmYWU4Ni1jNzEyLTQyZGYtYmViNi05Njc2MDM1OGI3OWYiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYxMywiZXhwIjoxNTk0NzI3MjEzfQ.st4MazPWe7S-Px-Nh-FB_xgigSiPW--PIuNM7PJjBmY
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: 42d875d2-0281-4203-a9a7-7ad5a3729f36
Content-Length: 1386

{
  "pageNumber" : 0,
  "pageCount" : 63,
  "nextPage" : 1,
  "pageSize" : 2,
  "totalCount" : 126,
  "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 /api/standingorders?page=2&size=2&sort=amount.instructedAmount.value&order=ASC HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:46:52 CEST
X-Request-ID: cdf901f5-3956-4708-9985-f51d52c34418
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJmNmYxZmE0Yy1hNmYxLTQ2YzYtOGVlNC1mYTk4Y2MwNGI3OGIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYxMCwiZXhwIjoxNTk0NzI3MjEwfQ.soDp9ZDJ3KKhzbaRtkQcne53xT4LqRaw33z6DESHyZE
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: cdf901f5-3956-4708-9985-f51d52c34418
Content-Length: 1522

{
  "pageNumber" : 2,
  "pageCount" : 63,
  "nextPage" : 3,
  "pageSize" : 2,
  "totalCount" : 126,
  "standingOrders" : [ {
    "standingOrderIdentification" : {
      "endToEndIdentification" : "endToEndId45343",
      "transactionIdentification" : "5976"
    },
    "amount" : {
      "instructedAmount" : {
        "value" : 0.5,
        "currency" : "EUR"
      }
    },
    "standingOrder" : {
      "alias" : "prvni SEPA trvalak",
      "execution" : {
        "mode" : "UNTIL_CANCELLATION",
        "modeDue" : "DUE_DAY_OF_MONTH",
        "interval" : "DAILY",
        "remitSkipCount" : 2
      }
    },
    "debtorAccount" : {
      "id" : "D5C2960C-D29B-4B8C-AEDD-7736035754F6",
      "identification" : {
        "iban" : "CZ9640000000007255060015"
      },
      "currency" : "EUR"
    }
  }, {
    "standingOrderIdentification" : {
      "instructionIdentification" : "TEST_STANDING_ORDER_PSD2",
      "transactionIdentification" : "8142"
    },
    "amount" : {
      "instructedAmount" : {
        "value" : 1.0,
        "currency" : "CZK"
      }
    },
    "standingOrder" : {
      "alias" : "TEST_STANDING_ORDER_ALIAS",
      "execution" : {
        "mode" : "UNTIL_CANCELLATION",
        "modeDue" : "DUE_OR_BEFORE_DAY_OF_MONTH",
        "interval" : "MONTHLY",
        "remitSkipCount" : 1
      }
    },
    "debtorAccount" : {
      "id" : "339382F0-2608-4E08-B9A6-4A28D1960790",
      "identification" : {
        "iban" : "CZ2140000000007255060007"
      },
      "currency" : "CZK"
    }
  } ]
}

Example sort by currency ASC and amount DESC

GET /api/standingorders?page=0&size=2&sort=amount.instructedAmount.currency,amount.instructedAmount.value&order=asc,desc HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:00 CEST
X-Request-ID: 70e82c4e-b275-4fe0-a768-322345d6804b
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIzYmZjN2RhNS1lN2Q3LTQxNmUtYTE5ZC0xYzJmNjQwMDIwZGUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYxOCwiZXhwIjoxNTk0NzI3MjE4fQ.-SWAqPcaxeIsGnnWh1OoG4oKs-ze-KOXLUVfc4OYA98
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: 70e82c4e-b275-4fe0-a768-322345d6804b
Content-Length: 1398

{
  "pageNumber" : 0,
  "pageCount" : 63,
  "nextPage" : 1,
  "pageSize" : 2,
  "totalCount" : 126,
  "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.

  • TOKEN_FEDERATED – user authorizes the payment on the bank page with code generated by Authenticator. Authenticator is physical device issued by the bank on client request. 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.

  • TOKEN_TPP – code is generated by Authenticator by user. Code 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 /api/payments/balanceCheck HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:20 CEST
X-Request-ID: 98daab6b-9027-4608-844a-61d8afa0f021
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4ZmYyNDQ2MS0wZmEzLTRiMDctYTFiNy01NDViMmZlZTljZmIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYzOCwiZXhwIjoxNTk0NzI3MjM4fQ.QeFRZ7-i4SZPUDd410n_hOQ-ZJEpT-bl6HTna-PYfck
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 628

{
  "exchangeIdentification" : "BC1594723640749",
  "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: 98daab6b-9027-4608-844a-61d8afa0f021
Content-Length: 117

{
  "exchangeIdentification" : "BC1594723640749",
  "responseIdentification" : 1594723641529,
  "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'] or ['TOKEN_TPP', 'TOKEN_FEDERATED']

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'] or ['TOKEN_TPP', 'TOKEN_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 /api/payments HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:39 CEST
X-Request-ID: bd11b93a-6271-42eb-9dd8-0f625f89e712
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJmNGY3MDU2Mi05OTQ4LTRiZTQtYjU5My1jNTFlMjIxNDkwNjEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY1NywiZXhwIjoxNTk0NzI3MjU3fQ.1k9Z4yiaLRyonRGwKAImAN1s0R956PaKQ84lzq2Qul8
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 720

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723659659"
  },
  "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: bd11b93a-6271-42eb-9dd8-0f625f89e712
Content-Length: 1001

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723659659",
    "transactionIdentification" : "TPSD004873425"
  },
  "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" : "baeb34bb-c38b-49a0-900f-cad4c94496e0"
  },
  "instructionStatus" : "ACTC"
}

Domestic with error

Request

POST /api/payments HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:04 CEST
X-Request-ID: 959dc76e-0751-41b9-ba3d-fed031643721
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJkOTg2ODJiZS01NDBkLTQyOWItODFhMS0zYTZhNGU2ZjYzYjciLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYyMiwiZXhwIjoxNTk0NzI3MjIyfQ.pbTWF2ghyXtjkpWbCABnEZaPbhF-K8geGcESgUnYR6s
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 719

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723624802"
  },
  "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: 959dc76e-0751-41b9-ba3d-fed031643721
Content-Type: application/json
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 /api/payments HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:34 CEST
X-Request-ID: cfa9e9dd-d259-44ad-88b8-1a293e4288eb
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI5NTI2ZjI5ZS1hODcwLTQwZmQtOGE4Mi1hOWFmMDBmMzUzZjUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY1MiwiZXhwIjoxNTk0NzI3MjUyfQ.9wLUZm4rSNFjVIeQSpu21Px94QDhzNUFIhyb2pwsTs0
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 641

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723652667"
  },
  "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: cfa9e9dd-d259-44ad-88b8-1a293e4288eb
Content-Length: 922

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723652667",
    "transactionIdentification" : "TPSD004873423"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "NORM",
    "serviceLevel" : {
      "code" : "DMCT"
    }
  },
  "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"
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "d1cbc116-9952-4070-a463-50c976d93fd8"
  },
  "instructionStatus" : "ACTC"
}

SEPA

Request

POST /api/payments HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:27 CEST
X-Request-ID: b992c2b6-c637-450b-9c0c-85724655de7d
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI3YWQ3MWE1Mi00ZDM0LTQxNTgtOTEyMC03NjUyYWYxNDEzZjUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY0NSwiZXhwIjoxNTk0NzI3MjQ1fQ.HMf6oBki5wdTAL_RrDyKfeHjG2eJUiTR8c9P_RcjYdc
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 1958

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723645857",
    "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: b992c2b6-c637-450b-9c0c-85724655de7d
Content-Length: 2239

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723645857",
    "endToEndIdentification" : "NOTPROVIDED",
    "transactionIdentification" : "TPSF000017949"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "HIGH",
    "serviceLevel" : {
      "code" : "ESCT"
    }
  },
  "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"
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "04a07e57-df02-4fd4-87fc-18a1ec3afd1a"
  },
  "instructionStatus" : "ACTC"
}

Foreign EEA

Request

POST /api/payments HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:44 CEST
X-Request-ID: f23ee81f-2b98-47bb-9543-11d095c8c49b
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwMjgxZTMwMC03MDZlLTQ2ODItOTExOS0yY2EwNmEzZjFkODMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY2MiwiZXhwIjoxNTk0NzI3MjYyfQ.exNvJ3kSxtSZ1ffuZQp3606TemYIr9imB6qM-oAjQYQ
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 994

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723662938"
  },
  "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: f23ee81f-2b98-47bb-9543-11d095c8c49b
Content-Length: 1275

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723662938",
    "transactionIdentification" : "TPSF000017950"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "NORM",
    "serviceLevel" : {
      "code" : "XBCT"
    }
  },
  "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"
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "e89d0afb-3919-4854-b7de-cfb3b7e5078b"
  },
  "instructionStatus" : "ACTC"
}

Foreign non EEA

Request

POST /api/payments HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:23 CEST
X-Request-ID: d154d330-9de7-4cb1-9599-3ac8d3fbfd05
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI5ZGM1NDM5Yy05Y2ViLTQ0NjgtOTI4ZC01YzkzZWJiZDZmOTAiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY0MSwiZXhwIjoxNTk0NzI3MjQxfQ.f7pzkfACgWzAPUl5K0IPVcBFA1xp89XmQB-TySKcHMA
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 1162

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723641785"
  },
  "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: d154d330-9de7-4cb1-9599-3ac8d3fbfd05
Content-Length: 1443

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723641785",
    "transactionIdentification" : "TPSF000017948"
  },
  "paymentTypeInformation" : {
    "instructionPriority" : "NORM",
    "serviceLevel" : {
      "code" : "XBCT"
    }
  },
  "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"
      }
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "527a51a7-68a2-49b4-b3e4-394b814c9674"
  },
  "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 8. /api/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 /api/payments/TPSD004873425/status HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:41 CEST
X-Request-ID: a8fffc15-8df1-4375-bfaa-7a9dab17d5fd
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: a8fffc15-8df1-4375-bfaa-7a9dab17d5fd
Content-Length: 34

{
  "instructionStatus" : "ACTC"
}

Payment info

A GET request to get an information about payment.

Path parameters

Table 9. /api/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'] or ['TOKEN_TPP', 'TOKEN_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 /api/payments/TPSD004873425 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:41 CEST
X-Request-ID: 088e6d03-63d1-42c5-9a2e-f61fa9f007b2
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJmNGY3MDU2Mi05OTQ4LTRiZTQtYjU5My1jNTFlMjIxNDkwNjEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY1NywiZXhwIjoxNTk0NzI3MjU3fQ.1k9Z4yiaLRyonRGwKAImAN1s0R956PaKQ84lzq2Qul8
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: 088e6d03-63d1-42c5-9a2e-f61fa9f007b2
Content-Length: 1001

{
  "paymentIdentification" : {
    "instructionIdentification" : "1594723659659",
    "transactionIdentification" : "TPSD004873425"
  },
  "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" : "baeb34bb-c38b-49a0-900f-cad4c94496e0"
  },
  "instructionStatus" : "ACTC"
}

Payment delete

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

Path parameters

Table 10. /api/payments/{paymentId}
Parameter Description

paymentId

Requested payment id

Example

DELETE /api/payments/TPSD004873425 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:41 CEST
X-Request-ID: ebb5cedc-1899-498b-8ef8-c930f6f66c34
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJmNGY3MDU2Mi05OTQ4LTRiZTQtYjU5My1jNTFlMjIxNDkwNjEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY1NywiZXhwIjoxNTk0NzI3MjU3fQ.1k9Z4yiaLRyonRGwKAImAN1s0R956PaKQ84lzq2Qul8
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: ebb5cedc-1899-498b-8ef8-c930f6f66c34

Payment signing

Authorization detail (I)

A GET request to get payment authorization detail

Path parameters

Table 11. /api/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'] or ['TOKEN_TPP', 'TOKEN_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 /api/payments/TPSD004873421/sign/77a82475-fe1d-47de-b8f9-61a93b76ce58 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:15 CEST
X-Request-ID: 95f40a9b-d9b3-4f94-a2de-7dca9d7413be
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhY2ExOTQ5MC0wNDFjLTQ1Y2EtODA4Yy1hMTY3ZWE0ODY3NTMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYzMiwiZXhwIjoxNTk0NzI3MjMyfQ.JOpQNKrsRi17ceSb7vwE8zMkwX1NRNYV9RNrSghcN9k
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: 95f40a9b-d9b3-4f94-a2de-7dca9d7413be
Content-Length: 148

{
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "77a82475-fe1d-47de-b8f9-61a93b76ce58"
  }
}

Authorization initiation (II)

A POST request to generate signature

Path parameters

Table 12. /api/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 /api/payments/TPSD004873421/sign/77a82475-fe1d-47de-b8f9-61a93b76ce58?testAuthCode=true HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:16 CEST
X-Request-ID: 98143f1e-785f-4064-a3e8-a27559172575
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhY2ExOTQ5MC0wNDFjLTQ1Y2EtODA4Yy1hMTY3ZWE0ODY3NTMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYzMiwiZXhwIjoxNTk0NzI3MjMyfQ.JOpQNKrsRi17ceSb7vwE8zMkwX1NRNYV9RNrSghcN9k
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 37

{
  "authorizationType" : "SMS_TPP"
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 98143f1e-785f-4064-a3e8-a27559172575
Content-Length: 212

{
  "authorizationType" : "SMS_TPP",
  "code" : {
    "prefix" : "KCH"
  },
  "signInfo" : {
    "state" : "CODE_GENERATED",
    "signId" : "77a82475-fe1d-47de-b8f9-61a93b76ce58",
    "scenario" : "SMS_TPP"
  }
}

Authorization initiation (III)

A PUT request to confirm signature

Path parameters

Table 13. /api/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 /api/payments/TPSD004873421/sign/77a82475-fe1d-47de-b8f9-61a93b76ce58 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:17 CEST
X-Request-ID: 75cbe397-2d8e-4450-85e4-37aece43fe01
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhY2ExOTQ5MC0wNDFjLTQ1Y2EtODA4Yy1hMTY3ZWE0ODY3NTMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzYzMiwiZXhwIjoxNTk0NzI3MjMyfQ.JOpQNKrsRi17ceSb7vwE8zMkwX1NRNYV9RNrSghcN9k
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 40

{
  "code" : {
    "code" : "0000"
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 75cbe397-2d8e-4450-85e4-37aece43fe01
Content-Length: 133

{
  "signInfo" : {
    "state" : "COMPLETED",
    "signId" : "77a82475-fe1d-47de-b8f9-61a93b76ce58",
    "scenario" : "SMS_TPP"
  }
}

New Standing order

A POST request to enter a standing order.

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

Object

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'] or ['TOKEN_TPP', 'TOKEN_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 /api/standingorders HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:49:17 CEST
X-Request-ID: 87dbcfce-1e9c-413f-905e-fdf0d53ea5c3
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwMjY0MzcxNy1jOGQyLTQxODAtYTFjZS0zYTFiMzk4MmY3ZmUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzc1NSwiZXhwIjoxNTk0NzI3MzU1fQ.ZDOoIE_B5cCvf8uJb56y66rRNj7p_8VuT_vZjobWpmg
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 955

{
  "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: 87dbcfce-1e9c-413f-905e-fdf0d53ea5c3
Content-Length: 317

{
  "standingOrderIdentification" : {
    "transactionIdentification" : "8324"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "DMCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "221f27bf-7822-40da-9290-243b7b3d0908"
  }
}

Foreign standing order

Request

POST /api/standingorders HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:48:40 CEST
X-Request-ID: 7806747e-f4d4-4ac2-845b-1f70285cef0a
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI2NDdkZWEyYi04MDU1LTRkMWUtOWJmMS01ZGYxN2RhZjhlY2YiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzcxOCwiZXhwIjoxNTk0NzI3MzE4fQ.mVyzxbhoEqAof869RiiJiHjqwdcIzOaRFYmFav2tGEc
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 1056

{
  "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"
    }
  },
  "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: 7806747e-f4d4-4ac2-845b-1f70285cef0a
Content-Length: 317

{
  "standingOrderIdentification" : {
    "transactionIdentification" : "8321"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "XBCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "a9beaf0c-f023-47b6-b607-346a3130f96d"
  }
}

Domestic with error, not supported execution exception

Request

POST /api/standingorders HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:48:43 CEST
X-Request-ID: ee0ab16f-1cd0-49e4-bd28-b04d2c9f60f5
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJjYjVkODc3OS1mNzEyLTQ2ZTQtODNkNy02YWM2MjEzOGRjZGUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzcyMSwiZXhwIjoxNTk0NzI3MzIxfQ.A0DvvNcr3yD37RTVssttioYs9kFh00MWZdXNwUGJ_tc
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 1022

{
  "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: ee0ab16f-1cd0-49e4-bd28-b04d2c9f60f5
Content-Type: application/json
Content-Length: 133

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

Domestic with error, not supported execution interval

Request

POST /api/standingorders HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:51:24 CEST
X-Request-ID: 08dc3cf0-c5fe-45f1-bd1a-36fd3041d685
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJjYjEyMjBiMi03MThiLTRkYWItODcyMy05MGQ5NDI4ZGI4NmMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzg4MiwiZXhwIjoxNTk0NzI3NDgyfQ.ENfHZMiYsMCwoKQkn1LmnUEdxq3IvCUMVvDHUDEfIoU
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 957

{
  "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: 08dc3cf0-c5fe-45f1-bd1a-36fd3041d685
Content-Type: application/json
Content-Length: 143

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

Domestic with error, wrong execution date

Request

POST /api/standingorders HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:49:41 CEST
X-Request-ID: 5e560856-4cc0-48d9-aced-e7483ac1d96a
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI0NWJhZmVlNS0zMTRkLTRlM2MtOGVmMy05YzVkMWE0NTllMTUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzc3OSwiZXhwIjoxNTk0NzI3Mzc5fQ.Fz8HX2NelXx2oeldFXuS766nnMV6sQDZuEU7meZ_hOU
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 955

{
  "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: 5e560856-4cc0-48d9-aced-e7483ac1d96a
Content-Type: application/json
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 /api/standingorders HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:51:04 CEST
X-Request-ID: 32ed4483-d726-4464-aa21-2823c4e9de35
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiYmE0M2RjOS1hYWVhLTQ3NWItOGEwMi01NDQ4NmFjNzU4MWIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzg2MiwiZXhwIjoxNTk0NzI3NDYyfQ.ISiIR5k2NIv4ftamtV8B7hWOrJH3tumzHLHToY9jsWE
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 947

{
  "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: 32ed4483-d726-4464-aa21-2823c4e9de35
Content-Type: application/json
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 14. /api/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

Object

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'] or ['TOKEN_TPP', 'TOKEN_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 /api/standingorders/8343 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:50:56 CEST
X-Request-ID: 846bf8be-b1b4-489d-beea-888eee01e58f
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIyMzE2ZGFiNi0xNmQ3LTRlYzEtOWE3OS1mMThkOWYyMzRlOWEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzg1MywiZXhwIjoxNTk0NzI3NDUzfQ.eN0LFadjzQxlsSbs0c6Fzz5nWrP9w01k-5XCSEBeBO8
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: 846bf8be-b1b4-489d-beea-888eee01e58f
Content-Length: 1218

{
  "standingOrderIdentification" : {
    "instructionIdentification" : "TEST_STANDING_ORDER_PSD2",
    "transactionIdentification" : "8343"
  },
  "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"
  },
  "creditorAccount" : {
    "identification" : {
      "iban" : "CZ6330300000000000000123"
    },
    "currency" : "CZK"
  },
  "remittanceInformation" : {
    "unstructured" : "Test sprava pro prijemce",
    "structured" : {
      "creditorReferenceInformation" : {
        "reference" : [ "VS:1000", "KS:2000", "SS:3000" ]
      }
    }
  },
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "eb85f5df-ffb6-4965-b36e-1819ff0925e8"
  }
}

Standing order status

A GET request to get standing order status.

Path parameters

Table 15. /api/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 /api/standingorders/8346/status HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:51:11 CEST
X-Request-ID: befb30e9-9b98-4ca7-b709-fc57afd4d61e
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIyNWNiZmRjNi1jMDM1LTQzZmMtOTg5OC0xMWEyNWFkMzA0MTkiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzg2OCwiZXhwIjoxNTk0NzI3NDY4fQ.Q-oXMm1WnJRiuCHlidU86AloauyPVmk-GVc3FAgdI48
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: befb30e9-9b98-4ca7-b709-fc57afd4d61e
Content-Length: 62

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

Example for not existing standing order

GET /api/standingorders/999999999 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:49:11 CEST
X-Request-ID: 7a796dba-4d41-40a3-9801-68a0093d37f0
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIwZGVkMWFiNC1lMGZiLTRkYmQtODYyYi02ODdkYjIzZjA2NWIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzc0OSwiZXhwIjoxNTk0NzI3MzQ5fQ.YZqmXvLgRkuN6ucAT9kBakF1be0_6Z_wFT_1b5fM_d0
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: 7a796dba-4d41-40a3-9801-68a0093d37f0
Content-Type: application/json
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 16. /api/standingorders/{transactionIdentification}
Parameter Description

transactionIdentification

Requested transaction identification

Example

DELETE /api/standingorders/8323 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:49:14 CEST
X-Request-ID: ac9e0713-38ba-49ae-9ddd-f5901e92a7b9
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhZWVjNWU1Yy1lOTcyLTQ2ZTItOWIzMy02MjM3MjFlMGRkOWIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzc1MiwiZXhwIjoxNTk0NzI3MzUyfQ.PCUa8VhRaeyEgB99_fWmTocPvpPS2Jt1HICd8jWOpXE
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: ac9e0713-38ba-49ae-9ddd-f5901e92a7b9

Standing order update

A PUT request to change standing order

Path parameters

Table 17. /api/standingorders/{transactionIdentification}
Parameter Description

transactionIdentification

Requested transaction identification

Example

PUT /api/standingorders/8328 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:49:38 CEST
X-Request-ID: 37214da0-9e00-43df-a2bc-45daecf6c6ef
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIzMmUxMWMwNS1mYTFhLTQzYmItODkwMC1jNWM3ODE4NjdiZGEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzc3NSwiZXhwIjoxNTk0NzI3Mzc1fQ.cROstZjAnaGC9wwz5XFbu43wBVHaG0L6joChtf5CcnE
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 954

{
  "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: 37214da0-9e00-43df-a2bc-45daecf6c6ef
Content-Length: 317

{
  "standingOrderIdentification" : {
    "transactionIdentification" : "8329"
  },
  "paymentTypeInformation" : {
    "serviceLevel" : {
      "code" : "DMCT"
    }
  },
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "762da268-f9d4-4393-bddc-78c3710d4e6e"
  }
}

Standing order signing

Authorization detail (I)

A GET request to get standing order authorization detail

Path parameters

Table 18. /api/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'] or ['TOKEN_TPP', 'TOKEN_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 /api/standingorders/8311/sign/c065b1f6-aac5-44b0-8bff-7cbf18b8f300 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:48:07 CEST
X-Request-ID: 1e6db540-7a0d-40c6-b3f6-b1d86f22faee
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhOWM4NGE5NC1jM2FlLTQyZTMtYmY3Yy1mNDQ0YWNiZjJiOGMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY4MywiZXhwIjoxNTk0NzI3MjgzfQ.yoZEtntBJwtFr-1A759B2fk1YdWcCGg3d3J65RSThnE
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: 1e6db540-7a0d-40c6-b3f6-b1d86f22faee
Content-Length: 148

{
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "c065b1f6-aac5-44b0-8bff-7cbf18b8f300"
  }
}

Authorization initiation (II)

A POST request to generate signature

Path parameters

Table 19. /api/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 /api/standingorders/8311/sign/c065b1f6-aac5-44b0-8bff-7cbf18b8f300?testAuthCode=true HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:48:07 CEST
X-Request-ID: de6876be-a4ed-49b4-b4fd-e9a676a16c45
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhOWM4NGE5NC1jM2FlLTQyZTMtYmY3Yy1mNDQ0YWNiZjJiOGMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY4MywiZXhwIjoxNTk0NzI3MjgzfQ.yoZEtntBJwtFr-1A759B2fk1YdWcCGg3d3J65RSThnE
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 37

{
  "authorizationType" : "SMS_TPP"
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: de6876be-a4ed-49b4-b4fd-e9a676a16c45
Content-Length: 212

{
  "authorizationType" : "SMS_TPP",
  "code" : {
    "prefix" : "BBT"
  },
  "signInfo" : {
    "state" : "CODE_GENERATED",
    "signId" : "c065b1f6-aac5-44b0-8bff-7cbf18b8f300",
    "scenario" : "SMS_TPP"
  }
}

Authorization initiation (III)

A PUT request to confirm signature

Path parameters

Table 20. /api/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 /api/standingorders/8311/sign/c065b1f6-aac5-44b0-8bff-7cbf18b8f300 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:48:08 CEST
X-Request-ID: 0f707171-3f53-4605-99f7-73206b7956ba
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhOWM4NGE5NC1jM2FlLTQyZTMtYmY3Yy1mNDQ0YWNiZjJiOGMiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzY4MywiZXhwIjoxNTk0NzI3MjgzfQ.yoZEtntBJwtFr-1A759B2fk1YdWcCGg3d3J65RSThnE
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 40

{
  "code" : {
    "code" : "0000"
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 0f707171-3f53-4605-99f7-73206b7956ba
Content-Length: 133

{
  "signInfo" : {
    "state" : "COMPLETED",
    "signId" : "c065b1f6-aac5-44b0-8bff-7cbf18b8f300",
    "scenario" : "SMS_TPP"
  }
}

New Batch payment

Notes:

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

  • batch payment can include domestic and foreign payments together

A POST request to enter a batch payment.

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'] or ['TOKEN_TPP', 'TOKEN_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 /api/batchpayments HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:44:11 CEST
X-Request-ID: 583fdb80-89d6-4190-bdf1-41636b53fcc4
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiNzM2Mjc4MC1lOWZiLTRiYjUtOTE1Zi05YTE5OTIyZTU1MjEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzQ0OSwiZXhwIjoxNTk0NzI3MDQ5fQ.1HvsCPX-NPOQ-Us2cweK22E7xQz_wdvD6dx_2bF3NhE
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 297

{
  "exchangeIdentification" : "658576010faf0a23dc",
  "instructionName" : "TestBatchPayment",
  "payments" : [ {
    "signId" : "a2adb096-a754-49c4-9b86-493ed80ba80e"
  }, {
    "signId" : "eef91160-8a85-4709-9a83-34f63608dbe5"
  }, {
    "signId" : "808b651b-2ec6-4d3a-9f34-a4f448469412"
  } ]
}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 583fdb80-89d6-4190-bdf1-41636b53fcc4
Content-Length: 220

{
  "transactionIdentification" : "d6e46f50-6845-4a39-be8b-f85a23a83f75",
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "842bb383-c412-4611-8e34-2c6593b96469"
  }
}

Batch payment with not existing payment sign id

Request

POST /api/batchpayments HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:42:47 CEST
X-Request-ID: ec875152-0a41-4ce8-b5e5-c32537281dfd
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI2MGZmMTVjOS03MTU1LTQ2ODAtOTA5MS02NmFiMmI2NGQxMGQiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzM2NCwiZXhwIjoxNTk0NzI2OTY0fQ.bTgOZj9zm0c9j1GVe9Wq_BLpK9kPP_8D73aa7p5BUWY
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 341

{
  "exchangeIdentification" : "658576010faf0a23dc",
  "instructionName" : "TestBatchPayment",
  "payments" : [ {
    "signId" : "15a504fc-11f6-4f90-a3e7-f8acb2b00a28"
  }, {
    "signId" : "0eb66ab2-fed9-46e4-988d-3039312bd2ce"
  }, {
    "signId" : "5c0057b8-db75-4570-b330-0b6522ef43e2"
  }, {
    "signId" : "NotExisting-ID-0000"
  } ]
}

Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
X-Request-ID: ec875152-0a41-4ce8-b5e5-c32537281dfd
Content-Type: application/json
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.

Path parameters

Table 21. /api/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

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

scenarios

Array

A set of possible authorization scenarios, e.g. ['SMS_TPP', 'SMS_FEDERATED'] or ['TOKEN_TPP', 'TOKEN_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 /api/batchpayments/e8f1f617-b883-4fbd-b5b9-817f3510110c/status HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:45:24 CEST
X-Request-ID: 6d04552e-91e7-4f42-8a1c-45626d2d9b5c
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI3ODdjNzBhMC00NzZiLTRiMWMtYjA1NS02MzdjYjEzMWFjOTkiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzUyMiwiZXhwIjoxNTk0NzI3MTIyfQ.pGR4B84UQT38Np1cLESoHVimyjL81HmtVHE-J25GGYI
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: 6d04552e-91e7-4f42-8a1c-45626d2d9b5c
Content-Length: 674

{
  "instructionStatus" : "ACTC",
  "payments" : [ {
    "transactionIdentification" : "4873417",
    "instructionStatus" : "ACTC",
    "signInfo" : {
      "state" : "OPEN",
      "signId" : "c0437570-9536-4821-a5eb-99cd6f52ac39"
    }
  }, {
    "transactionIdentification" : "4873418",
    "instructionStatus" : "ACTC",
    "signInfo" : {
      "state" : "OPEN",
      "signId" : "3bdb4721-0619-4bcc-b08c-6796046c7ad0"
    }
  }, {
    "transactionIdentification" : "4873419",
    "instructionStatus" : "ACTC",
    "signInfo" : {
      "state" : "OPEN",
      "signId" : "aa061a66-0eed-4956-9e81-afdb5102bb59"
    }
  } ],
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ]
}

Batch payment delete

A DELETE request to delete standing order

Path parameters

Table 22. /api/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 /api/batchpayments/868ca68b-7174-447e-94d0-1159d82a6114 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:44:45 CEST
X-Request-ID: 22001bfe-07db-48ad-80ba-6514a572684a
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJhYzQ3ODE2NS0xOWY1LTQyMDktYjJkMy0wZjBjNTU0MDhjMTgiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzQ4MywiZXhwIjoxNTk0NzI3MDgzfQ.IKhC0lut7Qi0UoUs1u26XlOub8uZdx2JBKtaUYMuAQo
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: 22001bfe-07db-48ad-80ba-6514a572684a

Example of deleting with instructions

DELETE /api/batchpayments/b7423840-5d4e-49b3-ba31-5db11ebe97fe?allInstructions=true HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:43:14 CEST
X-Request-ID: 83be86b8-a172-46c4-b18a-a1b83dc90def
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiOGFlN2Q5Zi1lOThjLTQ5MjItYTVhNS0xOTEyZGE0MmRiYjkiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzM5MiwiZXhwIjoxNTk0NzI2OTkyfQ.s3M67XgnucI_MpH75U45X2TiK54r270lX8fim1Mspzk
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: 83be86b8-a172-46c4-b18a-a1b83dc90def

Batch payment signing

Authorization detail (I)

A GET request to get batch payment authorization detail

Path parameters

Table 23. /api/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'] or ['TOKEN_TPP', 'TOKEN_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 /api/batchpayments/c2ad2eef-c352-4d6f-a484-19e8ffcf7b73/sign/16d85869-355c-4ba5-ab45-e48b8958fbc8 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:43:43 CEST
X-Request-ID: 52cdb028-7062-4251-be19-7f771daac809
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4YzA2Mjk1OS1lMTQ3LTQwN2MtYjVlYS1iZDgxOWYxOWVkMzAiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzQyMSwiZXhwIjoxNTk0NzI3MDIxfQ.mro0KWFXsJHStKRpRe_UFjcaosWhu2IM9j4hiZemHUU
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: 52cdb028-7062-4251-be19-7f771daac809
Content-Length: 148

{
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "16d85869-355c-4ba5-ab45-e48b8958fbc8"
  }
}

Authorization initiation (II)

A POST request to generate signature

Path parameters

Table 24. /api/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 /api/batchpayments/c2ad2eef-c352-4d6f-a484-19e8ffcf7b73/sign/16d85869-355c-4ba5-ab45-e48b8958fbc8?testAuthCode=true HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:43:44 CEST
X-Request-ID: 82368dd0-7b40-4d29-936d-b43071251deb
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4YzA2Mjk1OS1lMTQ3LTQwN2MtYjVlYS1iZDgxOWYxOWVkMzAiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzQyMSwiZXhwIjoxNTk0NzI3MDIxfQ.mro0KWFXsJHStKRpRe_UFjcaosWhu2IM9j4hiZemHUU
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 37

{
  "authorizationType" : "SMS_TPP"
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: 82368dd0-7b40-4d29-936d-b43071251deb
Content-Length: 212

{
  "authorizationType" : "SMS_TPP",
  "code" : {
    "prefix" : "MTC"
  },
  "signInfo" : {
    "state" : "CODE_GENERATED",
    "signId" : "16d85869-355c-4ba5-ab45-e48b8958fbc8",
    "scenario" : "SMS_TPP"
  }
}

Authorization initiation (III)

A PUT request to confirm signature

Path parameters

Table 25. /api/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 /api/batchpayments/c2ad2eef-c352-4d6f-a484-19e8ffcf7b73/sign/16d85869-355c-4ba5-ab45-e48b8958fbc8 HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:43:46 CEST
X-Request-ID: edd20188-a92a-4def-9f57-2871a9d01cd9
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4YzA2Mjk1OS1lMTQ3LTQwN2MtYjVlYS1iZDgxOWYxOWVkMzAiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbInBpc3AiLCJhaXNwIl0sImlhdCI6MTU5NDcyMzQyMSwiZXhwIjoxNTk0NzI3MDIxfQ.mro0KWFXsJHStKRpRe_UFjcaosWhu2IM9j4hiZemHUU
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 40

{
  "code" : {
    "code" : "0000"
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
X-Request-ID: edd20188-a92a-4def-9f57-2871a9d01cd9
Content-Length: 133

{
  "signInfo" : {
    "state" : "COMPLETED",
    "signId" : "16d85869-355c-4ba5-ab45-e48b8958fbc8",
    "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 /api/accounts/balanceCheck HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:20 CEST
X-Request-ID: 4dc52924-dcc5-403c-acac-ccdc3554e500
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 619

{
  "exchangeIdentification" : "BC1594723640361",
  "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: 4dc52924-dcc5-403c-acac-ccdc3554e500
Content-Type: application/json
Content-Length: 132

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

Example #2 - ok, declined, insufficient amount

POST /api/accounts/balanceCheck HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:20 CEST
X-Request-ID: a601cfe3-609f-48e6-982c-e00a69abd797
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 634

{
  "exchangeIdentification" : "BC1594723640413",
  "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: a601cfe3-609f-48e6-982c-e00a69abd797
Content-Length: 117

{
  "exchangeIdentification" : "BC1594723640413",
  "responseIdentification" : 1594723640486,
  "response" : "DECL"
}

Example #3 - ok, approved

POST /api/accounts/balanceCheck HTTP/1.1
Content-Type: application/json
Content-Type: application/json
Accept-Language: cs
Date: Tue, 14 Jul 2020 12:47:20 CEST
X-Request-ID: 55fe79a6-3688-4c0d-92c7-bd4232fc78a9
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json
Host: localhost:8080
Content-Length: 628

{
  "exchangeIdentification" : "BC1594723640537",
  "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: 55fe79a6-3688-4c0d-92c7-bd4232fc78a9
Content-Length: 117

{
  "exchangeIdentification" : "BC1594723640537",
  "responseIdentification" : 1594723640599,
  "response" : "APPR"
}