General notes

Documentation is subject to change without notice.

Localization

All requests will contain Accept-Language header reflecting user’s language set in browser. It will be used e.g. for correct language in error messages.

Accept-Language:cs

Dates

Dates are serialized into JSON as strings, We are using UTC and ISO 8601 Time zone format.

So, java.util.Date is converted using SimpleDateFormat yyyy-MM-dd’T’HH:mm:ss.SSSX

We live in CEST (Central European Daylight Savings Time) timezone, which is +2 of GMT. So, for example, date value with date only and no time is serialized like this:

2016-05-03 → 2016-05-02T22:00:00.000Z

And after deserialization using yyyy-MM-dd’T’HH:mm:ss.SSSX SimpleDateFormat you will get 2016-05-03 in CEST timezone.

you can also use just date yyyy-MM-dd

HTTP status codes

Status code Usage

200 OK

Operation ended sucessfully

400 Bad Request

When FIS-side validation fails. This status code contains error message(s) which are typically to be rendered to the client. See HTTP 400 Error message

404 Resource not found

When requested URL does not exists

500 Internal error

When there is some technical error (exception). This error is not to be rendered to the client.

Instead something like There is an technical error, please contact helpdesk should be displayed

something else

Some API uses other codes, then they are documented in these APIs. For example /login request returns 403 when login fails

HTTP 400 Error message

{
	"messages":[
		{
			"severity":"ERROR", (1)
			"message":"Counter Party is required"
		},
		{
			"severity":"ERROR",
			"message":"Spot margin must not be null",
			"errorCode":"EB-1001" (2)
		}
	],
	"severity":"ERROR"  (3)
}
1 as of now severity is always ERROR. Reserved for future use: WARN, INFO
2 If there is a need to custom handle error at your side (and not just display it to the client), Error will have a code to identify it.
3 Overall severity is worst case of all severities, so now it is always ERROR

End Points

PRODUCTION: https://api.maxbanka.eu

example:

https://api.maxbanka.eu/web/contact-form
https://api.maxbanka.eu/web/service-status

API

Currencies

A GET request to receive list of currency rates vs CZK

Path parameters

Table 1. /web/exchangerate/{rateType}/{bankingDate}
Parameter Description

rateType

one of CASH (valuty), MARKET (devizy)

bankingDate

date - current or history, format yyyy-MM-dd

Response fields

Path Type Description

[].currency

String

currency

[].buyRate

Number

Buy Rate

[].saleRate

Number

Sale Rate

[].midRate

Number

Mid Rate

[].quotationUnit

Number

Quotation Unit

[].country

String

Country of the currency

[].exportDate

String

Rate publish date

[].rateType

String

MARKET, CASH or STANDARD

[].customBuyRate

Number

Custom Buy Rate, filled in addition to buy rate

[].customSaleRate

Number

Custom Sale Rate, filled in addition to sale rate

Example

GET /web/exchangerate/MARKET/2019-01-14 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 3147

[ {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 27.03,
  "buyRate" : 26.489,
  "saleRate" : 27.571,
  "currency" : "EUR",
  "country" : "EU",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 24.127,
  "buyRate" : 23.644,
  "saleRate" : 24.61,
  "currency" : "USD",
  "country" : "USA",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 34.846,
  "buyRate" : 34.149,
  "saleRate" : 35.543,
  "currency" : "GBP",
  "country" : "Velká Británie",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 35.971,
  "buyRate" : 35.252,
  "saleRate" : 36.69,
  "currency" : "RUB",
  "country" : "Rusko",
  "quotationUnit" : 100
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 22.106,
  "buyRate" : 21.664,
  "saleRate" : 22.548,
  "currency" : "JPY",
  "country" : "Japonsko",
  "quotationUnit" : 100
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 24.435,
  "buyRate" : 23.946,
  "saleRate" : 24.924,
  "currency" : "CHF",
  "country" : "Švýcarsko",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 3.634,
  "buyRate" : 3.561,
  "saleRate" : 3.707,
  "currency" : "DKK",
  "country" : "Dánsko",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 2.912,
  "buyRate" : 2.854,
  "saleRate" : 2.97,
  "currency" : "SEK",
  "country" : "Švédsko",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 2.908,
  "buyRate" : 2.85,
  "saleRate" : 2.966,
  "currency" : "NOK",
  "country" : "Norsko",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 6.152,
  "buyRate" : 6.029,
  "saleRate" : 6.275,
  "currency" : "PLN",
  "country" : "Polsko",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 8.612,
  "buyRate" : 8.44,
  "saleRate" : 8.784,
  "currency" : "HUF",
  "country" : "Maďarsko",
  "quotationUnit" : 100
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 18.447,
  "buyRate" : 18.078,
  "saleRate" : 18.816,
  "currency" : "CAD",
  "country" : "Kanada",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 17.448,
  "buyRate" : 17.099,
  "saleRate" : 17.797,
  "currency" : "AUD",
  "country" : "Austrálie",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 8.206,
  "buyRate" : 8.042,
  "saleRate" : 8.37,
  "currency" : "TRY",
  "country" : "Turecko",
  "quotationUnit" : 1
}, {
  "exportDate" : "2016-06-16T11:15:46.213Z",
  "rateType" : "MARKET",
  "midRate" : 1.55,
  "buyRate" : 1.519,
  "saleRate" : 1.581,
  "currency" : "ZAR",
  "country" : "JAR",
  "quotationUnit" : 1
} ]

Contact form

A POST request to fill a contact form

Request fields

Path Type Description

name

String

first name, up to 50 cahracters

surname

String

last name, up to 50 cahracters

phone

String

phone number, up to 50 cahracters

email

String

email address, up to 50 cahracters, optional

date

String

requested date of contact, format yyyy-MM-dd or dd.MM.yyyy or dd/MM/yyyy, optional

time

String

requested time of contact, format HH:mm, optional

notes

String

message to the bank, up to 8000 characters, optional

dataProcessing

Boolean

consent to process data, must be checked

marketingConsent

Boolean

souhlas se zasíláním marketingových sdělení

preciousMetalConsent

Boolean

chci získávat informace o investicích do drahých kovů

cryptoCurrencyConsent

Boolean

chci získávat informace o kryptoměnách

businessInvestmentConsent

Boolean

chci získávat informace o investicích do společností

Example

POST /web/contact-form HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Content-Length: 354
Host: localhost:8080

{
  "name" : "Jan",
  "surname" : "Zelenka",
  "phone" : "602364938",
  "email" : "Zelenka.jan@gmail.com",
  "date" : "2023-08-14",
  "time" : "12:34",
  "notes" : "zprava bance - test, test",
  "dataProcessing" : true,
  "marketingConsent" : true,
  "preciousMetalConsent" : true,
  "cryptoCurrencyConsent" : true,
  "businessInvestmentConsent" : true
}
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 3

{ }

Service status

A GET request to get status of IB and PSD2 services.
If this API returns http status 200, then refer to status of individual services (status can be UP or DOWN)
if this API returns some error http status or is not available at all, consider all services DOWN

Response fields

Path Type Description

PSD2

String

UP - ok, DOWN - error

IB

String

UP - ok, DOWN - error

Example

GET /web/service-status HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 36

{
  "IB" : "UP",
  "PSD2" : "DOWN"
}

Special Rates

A GET request to receive special rates

Path parameters

Table 2. /web/specialrates/{bankingDate}
Parameter Description

bankingDate

date - current or history, format yyyy-MM-dd

Response fields

Path Type Description

expoMarketSaleEcbEurCzkDeviation

Number

expoMarketEurCzkSaleRate - ecbEurCzkFix

expoMarketSaleEcbEurCzkDeviationPercentage

Number

((expoMarketEurCzkSaleRate * 100) / ecbEurCzkFix) - 100

expoCardEcbCzkDeviationPercentage

Object

Deviation percentage for card transactions between Expo and ECB

Example

GET /web/specialrates/2023-08-14 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json
Accept-Language: cs
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Content-Length: 152

{
  "expoMarketSaleEcbEurCzkDeviation" : -24.103,
  "expoMarketSaleEcbEurCzkDeviationPercentage" : -100.0,
  "expoCardEcbCzkDeviationPercentage" : { }
}