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;charset=UTF-8
Accept: application/json;charset=UTF-8
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;charset=UTF-8
Content-Length: 518

{
  "application_type" : "web",
  "redirect_uris" : [ "https://tpp.cz" ],
  "client_name" : "TEST TPP",
  "logo_uri" : "https://tpp.cz/logo.png",
  "contact" : "admin@tpp.cz",
  "scopes" : [ "aisp", "pisp" ],
  "client_id" : "ef38b585-72fc-4132-9450-29e0a5d43656",
  "client_secret" : "cfJ284G0lQn3cwDtZEiu3GNZknLh4TwMiB9xueu4kRvamceYXC6zAWGjgsk9xU5E",
  "client_secret_expires_at" : 0,
  "api_key" : "2kY5iY7Z77dLa30DqhrvSCWWEsYhyMAFoMC8JotC898tEheEUDyli0QhGRVR0kg4",
  "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/ef38b585-72fc-4132-9450-29e0a5d43656 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 518

{
  "application_type" : "web",
  "redirect_uris" : [ "https://tpp.cz" ],
  "client_name" : "TEST TPP",
  "logo_uri" : "https://tpp.cz/logo.png",
  "contact" : "admin@tpp.cz",
  "scopes" : [ "aisp", "pisp" ],
  "client_id" : "ef38b585-72fc-4132-9450-29e0a5d43656",
  "client_secret" : "cfJ284G0lQn3cwDtZEiu3GNZknLh4TwMiB9xueu4kRvamceYXC6zAWGjgsk9xU5E",
  "client_secret_expires_at" : 0,
  "api_key" : "2kY5iY7Z77dLa30DqhrvSCWWEsYhyMAFoMC8JotC898tEheEUDyli0QhGRVR0kg4",
  "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/ef38b585-72fc-4132-9450-29e0a5d43656 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8
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;charset=UTF-8
Content-Length: 322

{
  "application_type" : "web",
  "redirect_uris" : [ "https://tpp2.cz" ],
  "client_name" : "TEST TPP 2",
  "logo_uri" : "https://tpp.cz/logo2.png",
  "contact" : "admin2@tpp.cz",
  "scopes" : [ "aisp", "pisp" ],
  "client_id" : "ef38b585-72fc-4132-9450-29e0a5d43656",
  "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/ef38b585-72fc-4132-9450-29e0a5d43656 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8
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/ef38b585-72fc-4132-9450-29e0a5d43656/renewSecret HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 180

{
  "client_id" : "ef38b585-72fc-4132-9450-29e0a5d43656",
  "client_secret" : "aQris8Rv1y0dkbXIRODwzYvWl3K461AunZSOnkl6Q5K8scGZA6Xx8zopBC7bsjfD",
  "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/ef38b585-72fc-4132-9450-29e0a5d43656/renewKey HTTP/1.1
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-----
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 140

{
  "client_id" : "ef38b585-72fc-4132-9450-29e0a5d43656",
  "api_key" : "S50MX7t0OoKxmNyNCTjyJgHVwtbHBobAsx689bnGRYMPoTsi96kwZGHm8wo0SOnH"
}

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=ef38b585-72fc-4132-9450-29e0a5d43656&scope=aisp&state=nejaky_state HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8
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=ef38b585-72fc-4132-9450-29e0a5d43656&scope=aisp&state=nejaky_state HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store

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

Request example

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

grant_type=authorization_code&code=J84ZFMR1KN883TRQ6IR8JWMCXFCR2HCUK4N84Y3CBPW3MQH72CPPUXJ43M3MVWJ9&client_id=ef38b585-72fc-4132-9450-29e0a5d43656&client_secret=cfJ284G0lQn3cwDtZEiu3GNZknLh4TwMiB9xueu4kRvamceYXC6zAWGjgsk9xU5E&redirect_uri=https%3A%2F%2Ftpp.cz

Response - ERROR

Path Type Description

error

String

Error code

error_description

String

Error description

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

{
  "error" : "ACCESS_DENIED"
}

Response - OK

Path Type Description

access_token

String

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

expires_in

Number

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

token_type

String

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

acr

String

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

refresh_token

String

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

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

{
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6ImJjYmNmOTFhLTdkZmItNDk5NC05ZDFjLWJlZmZlODRlMTE5OSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiJlZjM4YjU4NS03MmZjLTQxMzItOTQ1MC0yOWUwYTVkNDM2NTYiLCJzY29wZXMiOlsiYWlzcCIsInBpc3AiXSwiaWF0IjoxNTY5ODU4OTg1LCJleHAiOjE1Njk4NjI1ODV9.5400Viu08mD71PpcDsdQfInwDpn9m0ou3g5BUOMgoug",
  "refresh_token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6ImRjMGMzMTdiLWU2YzktNDRiMi05ZDYyLWRhZjlhZjk2MDkxNCIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiJlZjM4YjU4NS03MmZjLTQxMzItOTQ1MC0yOWUwYTVkNDM2NTYiLCJzY29wZXMiOlsiYWlzcCIsInBpc3AiXSwiaWF0IjoxNTY5ODU4OTg1LCJleHAiOjE1Nzc2Mzg1ODV9.8eLlMNSnlXJUligu_Qtt-dc0KAj9V2o3gPXTJ_uRw74",
  "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;charset=UTF-8
Accept-Language: cs
Host: localhost:8080

grant_type=refresh_token&client_id=ef38b585-72fc-4132-9450-29e0a5d43656&refresh_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6IjE0MjYwMzYzLTU4YmYtNDkyNy04MWI3LTkxMTg2MzYxY2MxYSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiJlZjM4YjU4NS03MmZjLTQxMzItOTQ1MC0yOWUwYTVkNDM2NTYiLCJzY29wZXMiOlsiYWlzcCIsInBpc3AiXSwiaWF0IjoxNTY5ODU4OTgzLCJleHAiOjE1Nzc2Mzg1ODN9.o6uih4mdkmReGQ8_I4vYmsp7N28Xlo2kKsFhLQtYaCQ
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 495

{
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6ImU5OGM1ZDBlLWU2MjUtNDFhYS05ZDI2LWE1MGYyMzM0OGQxZSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiJlZjM4YjU4NS03MmZjLTQxMzItOTQ1MC0yOWUwYTVkNDM2NTYiLCJzY29wZXMiOlsiYWlzcCIsInBpc3AiXSwiaWF0IjoxNTY5ODU4OTgzLCJleHAiOjE1Njk4NjI1ODN9.Gzx_-b1fxb8NTx_Tch3acRk679PxqBL1AoZzWdZqp8Y",
  "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;charset=UTF-8
Accept-Language: cs
Host: localhost:8080

token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCIsImp0aSI6IjE0MjYwMzYzLTU4YmYtNDkyNy04MWI3LTkxMTg2MzYxY2MxYSIsInVzZXJJZCI6MSwiY3VzdG9tZXIiOjEyOTQ4NiwiYWNjb3VudHMiOlt7ImFjY291bnRObyI6IioiLCJwZXJtaXNzaW9uIjoiQUNUSVZFIn1dLCJjbGllbnRfaWQiOiJlZjM4YjU4NS03MmZjLTQxMzItOTQ1MC0yOWUwYTVkNDM2NTYiLCJzY29wZXMiOlsiYWlzcCIsInBpc3AiXSwiaWF0IjoxNTY5ODU4OTgzLCJleHAiOjE1Nzc2Mzg1ODN9.o6uih4mdkmReGQ8_I4vYmsp7N28Xlo2kKsFhLQtYaCQ
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

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
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:16 CEST
X-Request-ID: a49c8dac-acf9-4271-a929-0af35dd35015
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4NjdiY2I1ZS01ZWIzLTQ2OGItODZiOS1kNTZjMWU1MWM4NGIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk3NiwiZXhwIjoxNTY5ODYyNTc2fQ.ZVKAxZ9ZMxI-1KggPt0z0S8yriysdwZXV9S0dq4o0mI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: a49c8dac-acf9-4271-a929-0af35dd35015
Content-Length: 1442

{
  "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"
  }, {
    "id" : "0A580141-DEC4-4DBC-84A2-E86578E77B84",
    "identification" : {
      "iban" : "CZ7440000000007255060023",
      "other" : "7255060023"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "NEO Účet"
  }, {
    "id" : "350C80CE-FF31-46C3-8378-E33D7D5C541D",
    "identification" : {
      "iban" : "CZ5240000000007255060031",
      "other" : "7255060031"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Expo Global"
  }, {
    "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" : "Běžný účet"
  } ]
}
Example #2 - sort currency
GET /api/accounts?sort=currency&order=asc HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:17 CEST
X-Request-ID: 1b2d85eb-a5f5-4082-b131-b724e9469c14
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4NjdiY2I1ZS01ZWIzLTQ2OGItODZiOS1kNTZjMWU1MWM4NGIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk3NiwiZXhwIjoxNTY5ODYyNTc2fQ.ZVKAxZ9ZMxI-1KggPt0z0S8yriysdwZXV9S0dq4o0mI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 1b2d85eb-a5f5-4082-b131-b724e9469c14
Content-Length: 1442

{
  "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"
  }, {
    "id" : "350C80CE-FF31-46C3-8378-E33D7D5C541D",
    "identification" : {
      "iban" : "CZ5240000000007255060031",
      "other" : "7255060031"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Expo Global"
  }, {
    "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" : "Běžný účet"
  }, {
    "id" : "D5C2960C-D29B-4B8C-AEDD-7736035754F6",
    "identification" : {
      "iban" : "CZ9640000000007255060015",
      "other" : "7255060015"
    },
    "currency" : "EUR",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Zaměstnanecký účet"
  } ]
}
Example #1 - sort currency desc, identification.other asc
GET /api/accounts?sort=currency%2Cidentification.other&order=desc%2Casc HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:17 CEST
X-Request-ID: 1b33264f-387f-47d5-8d76-d46acb952708
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4NjdiY2I1ZS01ZWIzLTQ2OGItODZiOS1kNTZjMWU1MWM4NGIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk3NiwiZXhwIjoxNTY5ODYyNTc2fQ.ZVKAxZ9ZMxI-1KggPt0z0S8yriysdwZXV9S0dq4o0mI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 1b33264f-387f-47d5-8d76-d46acb952708
Content-Length: 1442

{
  "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"
  }, {
    "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" : "Běžný účet"
  }, {
    "id" : "0A580141-DEC4-4DBC-84A2-E86578E77B84",
    "identification" : {
      "iban" : "CZ7440000000007255060023",
      "other" : "7255060023"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "NEO Účet"
  }, {
    "id" : "350C80CE-FF31-46C3-8378-E33D7D5C541D",
    "identification" : {
      "iban" : "CZ5240000000007255060031",
      "other" : "7255060031"
    },
    "currency" : "CZK",
    "servicer" : {
      "bankCode" : "4000",
      "countryCode" : "CZ",
      "bic" : "EXPNCZPP"
    },
    "productI18N" : "Expo Global"
  } ]
}

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
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:18 CEST
X-Request-ID: 1a2785d1-66d2-413e-af16-aa795188864f
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4NjdiY2I1ZS01ZWIzLTQ2OGItODZiOS1kNTZjMWU1MWM4NGIiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk3NiwiZXhwIjoxNTY5ODYyNTc2fQ.ZVKAxZ9ZMxI-1KggPt0z0S8yriysdwZXV9S0dq4o0mI
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 1a2785d1-66d2-413e-af16-aa795188864f
Content-Length: 1005

{
  "balances" : [ {
    "type" : {
      "codeOrProprietary" : {
        "code" : "TOTAL_AVAILABLE_BALANCE"
      }
    },
    "creditLine" : {
      "included" : true,
      "amount" : {
        "value" : 150000,
        "currency" : "CZK"
      }
    },
    "amount" : {
      "value" : 58969.32,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "CRDT",
    "date" : {
      "dateTime" : "2019-09-30T15:56:18.845Z"
    }
  }, {
    "type" : {
      "codeOrProprietary" : {
        "code" : "CURRENT_BALANCE"
      }
    },
    "amount" : {
      "value" : 85643.29,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "date" : {
      "dateTime" : "2019-09-30T15:56:18.845Z"
    }
  }, {
    "type" : {
      "codeOrProprietary" : {
        "code" : "OPENING_BALANCE"
      }
    },
    "amount" : {
      "value" : 85643.29,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "date" : {
      "dateTime" : "2019-09-29T22: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

Identifikační číslo platby přiřazené bankou.

transactions[].amount.value

Number

Částka platby v měně účtu, ke kterému se historie plateb generuje.

transactions[].amount.currency

String

Tato měna

transactions[].creditDebitIndicator

String

Indikace, zda se jedná o debetní platbu nebo kreditní platbu na účtu. Vyjádření, zda se jedná o debetní nebo kreditní platbu, je označeno jedním z níže uvedených kódů: DBIT: Na vrub CRDT: V ostatních případech

transactions[].reversalIndicator

Boolean

Indikace, zda se jedná o storno. Vyjádření, zda se jedná o storno či nikoliv, je označeno jedním z níže uvedených kódů: true: Jedná se o storno false: Nejedná se o storno

transactions[].status

String

Stav položky (odepsané nebo připsané platby) na účtu z pohledu banky. Ve výpise se zobrazují pouze zaúčtované položky, a to konstantou BOOK, anebo blokované položky, a to konstantou PDNG.

transactions[].bookingDate.date

String

Datum zpracování/zaúčtování platby bankou ve formátu ISODate, resp. ISODateTime, tj. YYYY-MM-DD, popř. YYYY-MM-DDThh:mm:ss.sTZD.

transactions[].valueDate.date

String

Datum splatnosti/valuty platby ve formátu ISODate, tj. YYYY-MM-DD

transactions[].bankTransactionCode.proprietary.code

Number

Kód bankovní transakce dle číselníku CBA - viz. COBS standard

transactions[].bankTransactionCode.proprietary.issuer

String

konstanta CBA

transactions[].entryDetails.transactionDetails.references.messageIdentification

String

Převzatá identifikace platby zadaná klientem při jejím iniciování

transactions[].entryDetails.transactionDetails.references.accountServicerReference

String

Bankovní reference přiřazená dané platbě

transactions[].entryDetails.transactionDetails.references.paymentInformationIdentification

String

Specificky symbol, u plateb z platebnich karet interni cislo karty

transactions[].entryDetails.transactionDetails.references.mandateIdentification

String

Konstantni symbol

transactions[].entryDetails.transactionDetails.references.endToEndIdentification

String

pro domaci platby variabilni symbol, prO SEPA platby SEPA reference

transactions[].entryDetails.transactionDetails.references.chequeNumber

String

pro karetní operace je zde uvedeno číslo karty s hvězdičkami. Číslo karty je uvedeno vždy ve formátu xxxxxxxxxxxx1234

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

Number

Původní/originální částka v měně, která byla klientem požadována převést.

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

String

Toto měna

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

Number

Částka a platby v měně účtu klienta, po přepočtu částky

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

String

Toto měna

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

String

Měna původní částky, která byla klientem požadována převést

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

String

Měna účtu

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

Number

Směnný kurz použitý při účtování platby

transactions[].entryDetails.transactionDetails.charges.bearer

String

Strana, která nese náklady spojené s poplatky: DEBT – všechny poplatky hradil plátce, CRED – všechny poplatky hradil příjemce, SHAR – poplatky jsou dělené mezi plátce a příjemce

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

String

Název plátce platby. Řídí se dle směru platby, vyplňuje se v případě protistrany.

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

String

Nestrukturovaný záznam poštovní adresy plátce, až 2 řádky

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

String

Číslo účtu plátce v mezinárodním formátu čísla účtu IBAN. Řídí se dle směru platby, vyplňuje se v případě protistrany.

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

String

Číslo účtu plátce v lokálním formátu čísla účtu.

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

String

Název příjemce platby. Řídí se dle směru platby, vyplňuje se v případě protistrany.

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

String

Nestrukturovaný záznam poštovní adresy příjemce, až 2 řádky

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

String

Číslo účtu příjemce v mezinárodním formátu čísla účtu IBAN. Řídí se dle směru platby, vyplňuje se v případě protistrany.

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

String

Číslo účtu příjemce v lokálním formátu čísla účtu.

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

String

BIC / SWIFT kód banky plátce. Řídí se dle směru platby, vyplňuje se v případě protistrany

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

String

Lokální formát kódu banky plátce

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

String

BIC / SWIFT kód banky příjemce. Řídí se dle směru platby, vyplňuje se v případě protistrany

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

String

Lokální formát kódu banky příjemce

transactions[].entryDetails.transactionDetails.purpose.proprietary

String

Účel platby

transactions[].entryDetails.transactionDetails.remittanceInformation.unstructured

String

Zpráva pro příjemce (komentář)

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

String

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

transactions[].entryDetails.transactionDetails.additionalTransactionInformation

String

Textový popis typu transakce

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=2019-03-30&page=0&size=10 HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:12 CEST
X-Request-ID: 4c593d17-19c2-4e41-a55a-005ec1e85f90
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI2NzE2OTdhYi1lMjYyLTQxMDEtOTY2My00NGIyNDA1OGNiNDAiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk3MiwiZXhwIjoxNTY5ODYyNTcyfQ.S8EQDYDrCF6EJg5qRkW8xXl8KoSeu9R5_6YlUXatC1A
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 4c593d17-19c2-4e41-a55a-005ec1e85f90
Content-Length: 21412

{
  "pageNumber" : 0,
  "nextPage" : 1,
  "pageSize" : 10,
  "transactions" : [ {
    "entryReference" : "001D11E192680001-TPSD004324696",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-25"
    },
    "valueDate" : {
      "date" : "2019-09-25"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004324696",
          "accountServicerReference" : "001D11E192680001",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11F192680001-TPSD004324669",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-25"
    },
    "valueDate" : {
      "date" : "2019-09-25"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004324669",
          "accountServicerReference" : "001D11F192680001",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11F192660003-TPSD004324130",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-23"
    },
    "valueDate" : {
      "date" : "2019-09-23"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004324130",
          "accountServicerReference" : "001D11F192660003",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E192630002-TPSD004323613",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-20"
    },
    "valueDate" : {
      "date" : "2019-09-20"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004323613",
          "accountServicerReference" : "001D11E192630002",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E192630001-TPSD004323607",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-20"
    },
    "valueDate" : {
      "date" : "2019-09-20"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004323607",
          "accountServicerReference" : "001D11E192630001",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E192600002-TPSD004322693",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-17"
    },
    "valueDate" : {
      "date" : "2019-09-17"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004322693",
          "accountServicerReference" : "001D11E192600002",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E192600001-TPSD004322686",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-17"
    },
    "valueDate" : {
      "date" : "2019-09-17"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004322686",
          "accountServicerReference" : "001D11E192600001",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11F192590001-TPSD004322653",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-13"
    },
    "valueDate" : {
      "date" : "2019-09-13"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004322653",
          "accountServicerReference" : "001D11F192590001",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E192560003-TPSD004322641",
    "amount" : {
      "value" : 100.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-13"
    },
    "valueDate" : {
      "date" : "2019-09-13"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TPSD004322641",
          "accountServicerReference" : "001D11E192560003",
          "endToEndIdentification" : "123456",
          "paymentInformationIdentification" : "879213546",
          "mandateIdentification" : "456789"
        },
        "amountDetails" : {
          "instructedAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            }
          },
          "counterValueAmount" : {
            "amount" : {
              "value" : 100.0,
              "currency" : "CZK"
            },
            "currencyExchange" : {
              "sourceCurrency" : "CZK",
              "targetCurrency" : "CZK"
            }
          }
        },
        "relatedParties" : {
          "creditorAccount" : {
            "identification" : {
              "other" : {
                "identification" : "2100073281"
              }
            }
          }
        },
        "relatedAgents" : {
          "creditorAgent" : {
            "financialInstitutionIdentification" : {
              "clearingSystemMemberIdentification" : {
                "memberIdentification" : "2010"
              }
            }
          }
        },
        "remittanceInformation" : {
          "unstructured" : "FA 2353452",
          "structured" : {
            "creditorReferenceInformation" : {
              "reference" : [ "VS:123456", "KS:456789", "SS:879213546" ]
            }
          }
        },
        "additionalTransactionInformation" : "Tuzemská platba elektronicky"
      }
    }
  }, {
    "entryReference" : "001D11E192550002-TIBD004322570",
    "amount" : {
      "value" : 1.0,
      "currency" : "CZK"
    },
    "creditDebitIndicator" : "DBIT",
    "reversalIndicator" : false,
    "status" : "BOOK",
    "bookingDate" : {
      "date" : "2019-09-12"
    },
    "valueDate" : {
      "date" : "2019-09-12"
    },
    "bankTransactionCode" : {
      "proprietary" : {
        "code" : 10000101000,
        "issuer" : "CBA"
      }
    },
    "entryDetails" : {
      "transactionDetails" : {
        "references" : {
          "messageIdentification" : "TIBD004322570",
          "accountServicerReference" : "001D11E192550002",
          "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"
      }
    }
  } ]
}

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 or element “signInfo.state” contains SECOND_SIGN_REQUIRED is returned in URI 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
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:01 CEST
X-Request-ID: 653f909c-2df3-408a-ad11-f9d2485b3e7f
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI1YjQzYjVlOS0zMjE5LTQ1ODYtOTcyYS1hOTJkM2E0MjMwZDYiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk2MCwiZXhwIjoxNTY5ODYyNTYwfQ.-oEUrU1Ft0hRG71_BHycy_uR_Q5yT9Ivktkc2KipQm4
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 631

{
  "exchangeIdentification" : "BC1569858961948",
  "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" : 1000
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 653f909c-2df3-408a-ad11-f9d2485b3e7f
Content-Length: 117

{
  "exchangeIdentification" : "BC1569858961948",
  "responseIdentification" : 1569858962447,
  "response" : "APPR"
}

New Payment

A POST request to enter a new payment.

Request fields

Path Type Description

paymentIdentification

Object

Max35Text Payment identification

paymentIdentification.instructionIdentification

String

Max35Text Instruction identification

paymentIdentification.endToEndIdentification

String

Max35Text End to end identification

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

TUZEM - AmountType3CZ Payment amount

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

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

Object

Max35Text Payment identification

paymentIdentification.instructionIdentification

String

Max35Text Instruction identification

paymentIdentification.endToEndIdentification

String

Max35Text End to end identification

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

TUZEM - AmountType3CZ Payment amount

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

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
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:08 CEST
X-Request-ID: cb67e0f7-1f08-4a44-8e4e-1f88bb9f9d06
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4ZmY1NTNmNC02NTFjLTQyOWItYmYxNS03YjY5M2IwYzBlM2UiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk2OCwiZXhwIjoxNTY5ODYyNTY4fQ.rHpQ4eOCCLbRSJujABMsfOmsYOyWAljoK3Yl-1Ix2aw
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 720

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858968417"
  },
  "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;charset=UTF-8
X-Request-ID: cb67e0f7-1f08-4a44-8e4e-1f88bb9f9d06
Content-Length: 1001

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858968417",
    "transactionIdentification" : "TPSD004324913"
  },
  "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" : "05b2990b-855a-43da-bcbd-e75b2a74b6af"
  },
  "instructionStatus" : "ACTC"
}

Domestic with error

Request

POST /api/payments HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:55:54 CEST
X-Request-ID: af9c7a88-51f2-4a9c-9392-d0a4067aa165
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI1ZjNjNzY4Ny04NjJjLTQzYzgtYmY4ZS1iZmU2MThhOTI3ZGUiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk1MywiZXhwIjoxNTY5ODYyNTUzfQ.2-FevVuCUsfd_BlchAlT68ZWrSV6n-IU9kWdwWX6CIw
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 719

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858954459"
  },
  "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: af9c7a88-51f2-4a9c-9392-d0a4067aa165
Content-Type: application/json;charset=UTF-8
Content-Length: 234

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

Domestic #2

Request

POST /api/payments HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:06 CEST
X-Request-ID: 2b23064c-774e-49b2-b6a2-fe0a645220df
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJjYmRiY2U1Yy00MjQ4LTQ3ZmItYTNkOC1iNjBiZWY1ZTQyMTkiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk2NiwiZXhwIjoxNTY5ODYyNTY2fQ._EjazGs0YIsGdktkWVgUsiRedWmaeylWL5SmxRPDcZw
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 641

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858966256"
  },
  "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;charset=UTF-8
X-Request-ID: 2b23064c-774e-49b2-b6a2-fe0a645220df
Content-Length: 922

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858966256",
    "transactionIdentification" : "TPSD004324911"
  },
  "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" : "2d7bc519-2821-4e52-9acc-c2c697e419e1"
  },
  "instructionStatus" : "ACTC"
}

SEPA

Request

POST /api/payments HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:04 CEST
X-Request-ID: da9d7b64-fa38-4f32-ab46-ecb34033ca16
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJmZDBkMWI5ZS1kMWEyLTQwZDItYTdhNi03OTcwZTIxOThiMmYiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk2MywiZXhwIjoxNTY5ODYyNTYzfQ.1gYIZ2IK12xRV5iILIMYDuJA6ePGEI-vburwz9VIe4c
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 1958

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858963708",
    "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;charset=UTF-8
X-Request-ID: da9d7b64-fa38-4f32-ab46-ecb34033ca16
Content-Length: 2239

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858963708",
    "endToEndIdentification" : "NOTPROVIDED",
    "transactionIdentification" : "TPSF000009435"
  },
  "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" : "217eeeec-3760-460d-a84b-c3e1ae92c832"
  },
  "instructionStatus" : "ACTC"
}

Foreign EEA

Request

POST /api/payments HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:10 CEST
X-Request-ID: e0bc471e-7246-40c8-b140-cd5fb6a02643
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiIyNDNkYzcwZi02ZWI2LTQyMzUtOTMyMi03YTY4YmY2N2M2ZWEiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk2OSwiZXhwIjoxNTY5ODYyNTY5fQ.e7MftlVmlZYHXb2Ok3BwASEIHhaXP5CWZ0F2hq2iHIM
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 994

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858969882"
  },
  "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;charset=UTF-8
X-Request-ID: e0bc471e-7246-40c8-b140-cd5fb6a02643
Content-Length: 1275

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858969882",
    "transactionIdentification" : "TPSF000009436"
  },
  "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" : "c714a635-9e28-4be6-a04f-6dc0fa5aa7b8"
  },
  "instructionStatus" : "ACTC"
}

Foreign non EEA

Request

POST /api/payments HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:03 CEST
X-Request-ID: fb563575-9600-43fc-81dc-9baf6ad83f33
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI3N2U1YzVjMS02NmE2LTRhZjEtYTE0MS01ZDU5MTNkZDNjYTAiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk2MiwiZXhwIjoxNTY5ODYyNTYyfQ.2_Bfhsfef1y1RXPMqidUbH87Dz3dc_7LRQhEVpaR0v4
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 1162

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858962629"
  },
  "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;charset=UTF-8
X-Request-ID: fb563575-9600-43fc-81dc-9baf6ad83f33
Content-Length: 1443

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858962629",
    "transactionIdentification" : "TPSF000009434"
  },
  "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" : "1e83291c-d59d-440d-8ef7-775777f73767"
  },
  "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/TPSD004324913/status HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:08 CEST
X-Request-ID: f3306486-30e5-4e72-bfe4-a537db0ca42a
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: f3306486-30e5-4e72-bfe4-a537db0ca42a
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

Object

Max35Text Payment identification

paymentIdentification.instructionIdentification

String

Max35Text Instruction identification

paymentIdentification.endToEndIdentification

String

Max35Text End to end identification

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

TUZEM - AmountType3CZ Payment amount

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

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/TPSD004324913 HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:09 CEST
X-Request-ID: 54d37b65-f61e-4a5d-a250-5fa96464abe1
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4ZmY1NTNmNC02NTFjLTQyOWItYmYxNS03YjY5M2IwYzBlM2UiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk2OCwiZXhwIjoxNTY5ODYyNTY4fQ.rHpQ4eOCCLbRSJujABMsfOmsYOyWAljoK3Yl-1Ix2aw
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 54d37b65-f61e-4a5d-a250-5fa96464abe1
Content-Length: 1001

{
  "paymentIdentification" : {
    "instructionIdentification" : "1569858968417",
    "transactionIdentification" : "TPSD004324913"
  },
  "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" : "05b2990b-855a-43da-bcbd-e75b2a74b6af"
  },
  "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/TPSD004324913 HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:09 CEST
X-Request-ID: 2ae57871-a83c-41fc-873c-ad874af1ba34
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiI4ZmY1NTNmNC02NTFjLTQyOWItYmYxNS03YjY5M2IwYzBlM2UiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk2OCwiZXhwIjoxNTY5ODYyNTY4fQ.rHpQ4eOCCLbRSJujABMsfOmsYOyWAljoK3Yl-1Ix2aw
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 2ae57871-a83c-41fc-873c-ad874af1ba34

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/TPSD004324909/sign/197ad9d8-4732-412e-a7e7-21f350ec4679 HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:55:59 CEST
X-Request-ID: 31350d42-c884-4db6-ae73-7051d3bab4ef
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiZWI1NjI4ZS05Y2ZlLTRkODQtYTY2YS02MDA2MjA3NTI3OTgiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk1OCwiZXhwIjoxNTY5ODYyNTU4fQ.6yh5NcbS-acVpIoCncCNGUk4u8UNTevwZ97e3Mqlz18
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 31350d42-c884-4db6-ae73-7051d3bab4ef
Content-Length: 148

{
  "scenarios" : [ "SMS_TPP", "SMS_FEDERATED" ],
  "signInfo" : {
    "state" : "OPEN",
    "signId" : "197ad9d8-4732-412e-a7e7-21f350ec4679"
  }
}

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/TPSD004324909/sign/197ad9d8-4732-412e-a7e7-21f350ec4679?testAuthCode=true HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:55:59 CEST
X-Request-ID: 7440d45f-baa6-4e4a-a6ab-05756cf60a03
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiZWI1NjI4ZS05Y2ZlLTRkODQtYTY2YS02MDA2MjA3NTI3OTgiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk1OCwiZXhwIjoxNTY5ODYyNTU4fQ.6yh5NcbS-acVpIoCncCNGUk4u8UNTevwZ97e3Mqlz18
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 37

{
  "authorizationType" : "SMS_TPP"
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 7440d45f-baa6-4e4a-a6ab-05756cf60a03
Content-Length: 212

{
  "authorizationType" : "SMS_TPP",
  "code" : {
    "prefix" : "MBT"
  },
  "signInfo" : {
    "state" : "CODE_GENERATED",
    "signId" : "197ad9d8-4732-412e-a7e7-21f350ec4679",
    "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/TPSD004324909/sign/197ad9d8-4732-412e-a7e7-21f350ec4679 HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:00 CEST
X-Request-ID: 089bd9c1-a5d5-4f59-b745-83b1e3296a69
User-Involved: true
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJURVNUIFRQUCAyIC0gTkVNQVpBVCAhISEiLCJqdGkiOiJiZWI1NjI4ZS05Y2ZlLTRkODQtYTY2YS02MDA2MjA3NTI3OTgiLCJ1c2VySWQiOjEsImN1c3RvbWVyIjoxMjk0ODYsImFjY291bnRzIjpbeyJhY2NvdW50Tm8iOiIqIiwicGVybWlzc2lvbiI6IkFDVElWRSJ9XSwiY2xpZW50X2lkIjoiMDY4MDIwZjYtNDYzMS00NzA1LWFhZTgtM2VlNmU5ZmI4NDRiIiwic2NvcGVzIjpbImFpc3AiLCJwaXNwIl0sImlhdCI6MTU2OTg1ODk1OCwiZXhwIjoxNTY5ODYyNTU4fQ.6yh5NcbS-acVpIoCncCNGUk4u8UNTevwZ97e3Mqlz18
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 40

{
  "code" : {
    "code" : "0000"
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 089bd9c1-a5d5-4f59-b745-83b1e3296a69
Content-Length: 133

{
  "signInfo" : {
    "state" : "COMPLETED",
    "signId" : "197ad9d8-4732-412e-a7e7-21f350ec4679",
    "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
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:01 CEST
X-Request-ID: 2c442eb9-683d-4429-8ae9-794e1861ee73
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 619

{
  "exchangeIdentification" : "BC1569858961305",
  "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: 2c442eb9-683d-4429-8ae9-794e1861ee73
Content-Type: application/json;charset=UTF-8
Content-Length: 132

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

Example #2 - ok, declined, insufficient amount

POST /api/accounts/balanceCheck HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:01 CEST
X-Request-ID: d3e8fb71-c0e4-4ed8-966f-ec40fc84163e
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 634

{
  "exchangeIdentification" : "BC1569858961398",
  "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;charset=UTF-8
X-Request-ID: d3e8fb71-c0e4-4ed8-966f-ec40fc84163e
Content-Length: 117

{
  "exchangeIdentification" : "BC1569858961398",
  "responseIdentification" : 1569858961534,
  "response" : "DECL"
}

Example #3 - ok, approved

POST /api/accounts/balanceCheck HTTP/1.1
Accept-Language: cs
Content-Type: application/json
Date: Mon, 30 Sep 2019 17:56:01 CEST
X-Request-ID: 40f5f4f7-b2cc-4f01-b6de-059aa3cc03d0
User-Involved: false
API-key: fGji1GWUA4zQKLEEN9utjfVl3PDQdbJhB5bMhNNDrnSoxay23yHcKnbYCWkxnyuI
TPP-Name: TEST TPP 2
TPP-Identification: TPP legal identity
Accept: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 631

{
  "exchangeIdentification" : "BC1569858961568",
  "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" : 1000
  }
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
X-Request-ID: 40f5f4f7-b2cc-4f01-b6de-059aa3cc03d0
Content-Length: 117

{
  "exchangeIdentification" : "BC1569858961568",
  "responseIdentification" : 1569858961679,
  "response" : "APPR"
}