Air Bank OpenAPI - AirBank Extension

API Endpoint

This is documentation of the Airbank Extension services of Air Bank OpenAPI.

Versions

Version num. Link Valid from Valid to
0 documentation 13.1.2018

There are some rules that are valid throughout whole API.

Naming conventions

  • we use camelCase for all object and property names

  • we use plural in resource names

Paging

  • some resources (stated in documentation) that return collection of objects support pagination.

  • on request:

    • query parameter limit specifies maximum number of objects in returned collection
    • query parameter after specifies last object retrieved in previous request. Its value is usually id of last object retrieved in previous call, but this will be stated in documentation. Parameter after is used when traversing collection forwards.
    • query parameter before specifies first object retrieved in previous request (analogy to after parameter), and is used when traversing collection backwards.
    • if before and after are omitted, beginning of collection is returned, using specified sort order
    • items in collection are always sorted accoridng to attribute which could be passed in after/before parameters. Even if you specify different sorting order, this attribute will be last sorting criterion; if you do not specify sorting order, result collection will be sorted according to this attribute.

  • on response:

    • pagingInfo object is returned as part of response body with following attributes:
      • nextPage - request to retrieve next page. Either nextPage or previousPage is returned, depending whether you specify after or before parameter. If you specify neither before nor after parameter, these attributes will be omitted from response.
      • prevPage - request to retrieve previous page (see nextPage attribute description above).
      • itemsPerPage - number of items per page

Example request:

curl -X GET https://api.airbank.cz/openapi/banking/v1/transactions?sort=category&limit=10&after=15

Example response pagingInfo:

"pagingInfo": {
    "nextPage": "transactions?sort=category&limit=10&after=25"
    "itemsPerPage": 10,
}

Sorting

  • some resources (stated in documentation) suppors result sorting. You can specify sorting attributes and order using sort request parameter. For ascending order, specify just attribute name; for descending order, add unary - in front of attribute name. You can specify multiple attributes for sorting, separated by comma.

  • each resource that supports sorting specifies list of attributes that can be used for sorting.

Examples:

  • /openapi/public/fxrates?sort=currencyCode - get list of FX rates sorted by attribute currencyCode

  • /openapi/public/branches?sort=-name - get list of branches, sorted by attribute name in descending order

  • /openapi/banking/accounts?sort=accountType,-accountCurrency,accountName - get list of accounts, sorted by type (ascending), then by currency descending and then by account name (ascending)

Filtering

Some resources (stated in documentation) supports results filtering. Such resources have list of filters specified together with possible operations and possible values.

You can specify filtering by passing filter attribute. General pattern to specify filter is:

<filterName>|<operator>|<values>

  • filterName - filter name from documentation

  • operator - operator, specified in resource documentation

  • values - one or more values for filter. Multiple values are separated by comma

Multiple filters can be specified on each request, separated by semi-colon. They are joined by “AND”, so each result item must satisfy all conditions.

Filtering examples

  • get a list of incoming transactions
GET /openapi/banking/transactions?filter=direction|eq|INCOMING
  • get a list of transactions with category in (1, 5, 10)
GET /openapi/banking/transactions?filter=category|in|1,5,10
  • get a list of transactions with valueDate in (2016-02-10, 2016-04-28>
GET /openapi/banking/transactions?filter=valueDate|gt|2016-02-10;valueDate|lteq|2016-04-28

List of operators

operator meaning
lt less than
lteq less than or equals
eq equals
gteq greater than or equals
gt greater than
in value in list

API calls limits

When limit is reached, you receive HTTP error 429. To inform you about limits we use following headers:

  • X-Rate-Limit-Limit - The number of allowed requests in the current period

  • X-Rate-Limit-Remaining - The number of remaining requests in the current period

  • X-Rate-Limit-Reset - The number of seconds left in the current period

Bandwith usage reducing

Fields attribute

  • for all GET resources, you can use optional fields query parameter to limit objects’ attributes returned in response

  • fields parameter contains comma-separated list of attributes, that will be present in response; if omitted, all objects’ attributes will be returned

  • you can specify only top-level attributes in fields parameter. This means that when response is an object, you can only specify top-level attributes. When response is an array of objects, only top-level attributes of those objects can be specified.

  • if you specify non-existent attribute or atttribute that is not in first level, you will receive HTTP status 400 Bad Request

  • fields parameter has no effect on resources that returns plain value or array of plain values.

Examples:

  • /openapi/public/branches?fields=id,name,location - only get list of branches with id, name and location attributes

GZIP compression

  • we support GZIP compression of responses. Client must specify header Accept-Encoding: gzip in request in order to use the compression.

Versioning

We use API version in URL (e.g. https://api.airbank.cz/openapi/banking/v1/accounts). Minor changes (see below) that don’t break backwards compatibility do NOT increase API version, e.g. they may happen without prior notice and your application should be ready to handle them.

Minor changes include:

  • adding new resource

  • adding new optional header/URL parameter or optional body attribute to request

  • adding new attribute to response body

  • adding new error codes and messages, provided that error structure is the same

Language

We use English.

Response encoding

Unless stated otherwise, all responses are sent as Content-Type: application/json;charset=UTF-8

HTTP status codes

We use following status codes throughout the API, except for OAuth flow when response codes are prescribed in RFC

  • 200 OK - request was successful

  • 201 Created - request was successfull and resource was created

  • 204 No content - we accepted your request but there is nothing to return (e.g. response is empty)

  • 400 Bad Request - syntax error, e.g. request is missing required parameters/attributes or parameter values are of incorrect type

  • 401 Unauthorized - your API key is wrong or user not authorized (not logged in)

  • 403 Forbidden - access denied (e.g. user / application is not allowed to use the resource)

  • 404 Not Found - resource could not be found

  • 405 Method Not Allowed - specified method is not allowed for resource

  • 422 Unprocessable Entity - validation (semantic) errors. Request is well-formed, but cannot be processed (e.g. payment due date is in past). Errors are specified in response body (see below)

  • 429 Too Many Requests - you exceeded the rate limit (see API usage limits below)

  • 500 Internal Server Error - something went wrong on our side

  • 503 Service Unavailable - there is planned service outage (TODO: should specify response headers with more details on service outage)

API usage limits

Our API has usage limits, meaning number of API calls that your application can perform during specified time period. On each call, your app wil receive currently set limits and remaining quotas in following headers:

X-RateLimit-Limit-[API_NAME]-Minute: 10 - currently set limit of API calls

X-RateLimit-Remaining-[API_NAME]-Minute: 9 - remaining limit of API calls in given time period

If you exceed limits set for your application, you will receive HTTP status 429 with empty body.

Error handling

Besides HTTP status codes, which are the main indication if something goes wrong, we also use errors object to report more details about errors.

Errors object example:

{
    ...

    errors: [
        {
            "code": "ERR_100,
            "message": "Invalid contract number",
            "severity": "ERROR",
            "attribute": "partyAccount.accountNumber",          // optional
            "ticketId": "UAT1:AMS:20160516-091658.450:45e4" // optional
        },
        {
            "code": 352,
            "message": "Insufficiend funds for payment order realization",
            "severity": "WARN"
        },
        {
            "code": 523,
            "message": "This order will trigger currency exchange operation",
            "severity": "INFO"
        }
    ]
}

Error object attributes

attribute name description
code unique error code
message human readable error description (non-localized)
severity error severity (see below)
attribute json path of request attribute that caused the error (optional)
ticketId internal ticket ID, used for error backtracking

There are 3 levels of error severity:

  • ERROR - critical error, execution cannot continue.

  • WARN - non-critical error, execution can continue but further user interaction is advisable (for request to proceed, you MUST specify this error code in override request attribute).

  • INFO - information only, execution can continue without user interaction.

Most important error codes

  • OBJECT_NOT_FOUND - Cannot find required object

  • OBJECT_IN_WRONG_STATE - Cannot perform requested operation in current objects’ state (e.g. withdrawal code cannot be resend because it is inactive, or payment order cannot be edited)

  • INVALID_REQUEST - There are syntax errors in request (missing required parameter, wrong attribute value etc.)

  • FILTER_ERROR - There is an error in filter specification

  • SORT_ERROR - There is an error in sorting specification

  • GENERAL_ERROR - Unspecified (usually unexpected) error; use ticketId attribute to report it.

Formats

  • date and time uses ISO 8601 formatting, e.g.:

    • date is represented as YYYY-mm-dd. Timezone is added when necessary.
    • time is represented as Thh:mm:ss. Timezone is added when necessary.
    • day of week is represented as number 1…7, with 1 being Monday
    • week no. 1 is the week with the year’s first Thursday in it

  • phone numbers uses international format starting with ‘+’ and including country code

  • numbers format number format is defined by JSON standard, e.g. decimals are separated by .

Security

Security concept of Open API

Security is our key concern. To allow you use our API securely, we divide API resources into three groups, each requiring different level of security.

Public services - prefix /openapi/public

To use public services like list of branches, you need a valid API key. There is no need for users of your application to log in, or even have any agreement with us.

Banking services - prefix /openapi/banking

To use banking services like list of accounts or transactions history, you need a valid OAuth2 access token. Chapter Authentication describes how to get and use it.

Sensitive banking operations - prefix /openapi/banking, stated in documentation

Some extra sensitive banking operations (like entering a payment) requires additional user authorization, on top of valid OAuth2 token. Authorization mechanism is described in chapter Authorization.

Certficates

You need to include a valid user (client SSL) certificate to access all the API resources (except Public APIs). The certificate must be issued according RTS Commission Delegated Regulation (EU) 2018/389.

You must use this client SSL certificate when registering an application with /oauth2/register and then for calling any /oauth2/* resource.

We currently support formats from following certification authorities:

If you have a certificate that has different format and is issued by approved certification authority, please contact us.

API key and Client ID & Secret

OAuth2 client_id, client_secret and api_key for accessing protected services can be created by calling the /oauth2/register endpoint.

Notice: API key from /oauth2/register intended for using for calling some services with oauth2 (not for public sevices (/openapi/public/*).

Obtaining API key (for public services only)

You can get API Key in Developers portal for accessing public services (e.g. services that are not bound to current user).

Important: Keep your production API keys safe, as it will identify your application, counts to resource usage limits etc.

Using API key (for public services only)

API key is a 30 character string, that must be passed on each API call in header field called apikey. Example:

curl -H "apikey: 62eb165c070a41d5c1b58d9d3d725ca1" https://api.airbank.cz/openapi/public/branches
  • if you fail to specify apikey, you will receive 401 Unauthorized error and following response body:
{"message":"No API Key found in headers, body or querystring"}
  • if you provide invalid apikey, you will receive 403 Forbidden error and following response body:
{"message":"Invalid authentication credentials"}

Authentication

To access user sensitive data through API (use /openapi/banking, accountInfo, etc… resources), user must grant your application a permission to do so. Open API uses OAuth2 mechanism to grant permissions to access user data. As for now, only authorization code grant flow is supported. This section describes mechanism and resources to get valid access token and use it to access protected resources.

  • if you fail to specify OAuth2 token, you will receive 401 Unauthorized error and following response body:
{
   "error_description": "The access token is missing",
   "error": "invalid_request"
}
  • if you provide invalid OAuth2 token, you will receive 401 Unauthorized error and following response body:
{
    "error_description":"The access token is invalid or has expired",
    "error":"invalid_token"
}

Developers perspective

  1. Register your application at developers portal and request access to OAuth2 protected resources. You have to provide (beside others) redirect URI attribute - this is the URI user is redirected to after he logs in and approves your application (see below to learn more). You will receive client ID, client secret and API key(note: those are different than apikey, used to access any resource from public Open API).

  2. When you wish to access protected resource (pretty much anything under /openapi/banking,accountInfo, etc… path) for the first time, redirect user to login page with parameters:

    • client_id - client ID parameter you received from previous step
    • response_type - only value code is supported
    • state - random value that will be returned to you. You should check the value received on successfull redirect back to your app. Setting the state parameter is optional, but highly recommended
    • redirect_uri - Optional parameter. If you have more than one URL registered with your application, you can select one forwarding address. The redirect_uri parameter must start as at least one URL from the collection of URLs registered with your application. If the redirect_uri parameter is not specified, the first URL to be redirected from the application is used.

    Example login request:

    https://ib.airbank.cz/?client_id=MYID&response_type=code&state=ehshvnajgtf34

    IMPORTANT NOTE: Do not use embedded webview in mobile applications, use platform native browser instead.

  3. User have to log-in using his bank identity and approve your application’s access

  4. If successfull, user is redirected to redirect URI you specified at application registration, together with parameter code. This redirect should be handled by your application, in order to exchange code for valid access token; for mobile applications, consider using custom URL scheme (iOS), intents (Android) or similar mechanism.

    Example redirect URI:

    https://myapp.example.com/handle_authentication?code=123arjdmvcskfm&state=ehshvnajgtf34

  5. Upon receiving redirect URI on successfull authentication, you have to check state parameter - it has to be the same as you passed to login page. If it differs, you should not continue.

  6. Access API token resource and exchange code for access token. You will also receive refresh token; you can use it to get new access token when access token validity expires.

  7. You receive access token that has limited lifespan (usually to 20 min or so), along with refresh token. Refresh token can later be used to exchange for new access token, when old one expires.

  8. Use retireved access token to access protected resources by specifying it in header Authorization, together with its type, e.g.:

    curl -H "Authorization: Bearer access_token" https://apiendpoint/openapi/banking/profile

IMPORTANT NOTES:

  • You must keep your client secret safe. It serves as your application password.
  • Starting from 27 July 2023, refresh token validity is extended from 90 to 180 days.

User perspective

  1. User runs your application for the first time

  2. Your application redirects user to Open API login page

  3. User provides its credentials (user + password, possibly combined with another factor like SMS code etc)

  4. User sees a page, that displays details about your application and rights it requested.

  5. User authorizes your application’s access and he can start using your application.

Authentication resources

resource environment address
login page production https://ib.airbank.cz
token resource production /oauth2/token

Authorization

Sensitive active operations (such as placing a payment order) requires additional authorization, besides existing OAuth2 token. Such resources are marked in documentation. This section describes mechanism and resources used for authorization.

Currently there are two methods of authorization supported:

  • redirecting user to a bank authorization page and grab the authorization result behind the scenes - this is the default and always available method

  • use API resources to initiate and grab the authorization result - this method is only allowed when certain conditions are met (such as user approved authorization methods etc.)

Authorization object

Parameters of authorization are returned as a result of sensitive active operation (e.g. by creating/updating payment order). Authorization object has following structure:

  • authorizationId: aobrCdeU1Yu4HG_sKQe_uP25B0CYz7hsPYK_w9uF41ZK90KE9mANj (string, required) - internal authorization request identifier, expect arbitrary long string.

  • authResultURL: /openapi/banking/authorization/aobrCdeU1Yu4HG_sKQe_uP25B0CYz7hsPYK_w9uF41ZK90KE9mANj (string, required) - resource used to GET authorization result

  • mustRedirect: false (boolean, required) - if set to true, application must redirect user to redirectURL to complete authorization

  • redirectURL: https://www.airbank.cz/authorization/aobrCdeU1Yu4HG_sKQe_uP25B0CYz7hsPYK_w9uF41ZK90KE9mANj (string, required) - redirect URL for fallback authorization or for redirecting if mustRedirect is set to true

  • status: IN_PROGRESS (string, required) - authorization status. If status is AUTHORIZED, you can fetch the result by calling appropriate resource.

When mustRedirect is set to true, your app MUST use the redirect method to complete authorization.

Redirect user to bank authorization page

Authorization flow is handled completely by a web page provided by bank. All your app have to do is to redirect user to redirectURL, which initiates the authorization flow. You SHOULD provide query parameter callbackURL to the authorization web page; user will be redirected to this callbackURL when authorization finishes. This callbackURL MUST be registered in developers portal with corresponding application.

You will get the authorization result by calling authResultURL resource after your app gets notified by the redirection.

Use API resources to do the authorization

Alternative method, which is only available when mustRedirect attribute is set to false. Authorization flow is started by active operation itself, and all your app have to do is regularly poll authResultURL resource to retrieve authorization result. Your application SHOULD provide some indication to user that authorization is in progress. Your application SHOULD always provide means to access default authorization method of redirecting to bank authorization page, as this alternative method availability may vary by user.

Security resources

This is the resources used to support security concepts described above.

Application registration

POST /oauth2/register
Requestsexample 1
Body
{
"client_name": "Application Name",
"redirect_uris" : [
"https://ib.airbank.cz/paired",
],
"scopes" : [
  "PISP",
  "AISP",
  "CISP"
]
}
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "client_id": "4224c721d0bf47a5a109250db484e0e8",
  "client_secret": "5527f7a57202424f9ed5cc00e8b300fd",
  "api_key": "6667f7a57202424f9ed5cc00e8b666fd"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "client ID used to retrieve OAuth2 token"
    },
    "client_secret": {
      "type": "string",
      "description": "client secret used to retrieve OAuth2 token"
    },
    "api_key": {
      "type": "string",
      "description": "key to identify API calling"
    }
  },
  "required": [
    "client_id",
    "client_secret",
    "api_key"
  ]
}

Application registration
POST/oauth2/register

This resource is used to register an application before accessing other API endpoints. Included scopes must be a subset of these included in an user certificate.

It is not possible to update the application. If you want to update the application record, delete the existing application and register a new one.

Application info

GET /oauth2/register/4224c721d0bf47a5a109250db484e0e8
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "client_id": "4224c721d0bf47a5a109250db484e0e8",
  "client_secret": "5527f7a57202424f9ed5cc00e8b300fd",
  "api_key": "6667f7a57202424f9ed5cc00e8b666fd",
  "redirect_uris": [
    "https://ib.airbank.cz/paired"
  ],
  "client_name": "Application Name"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "client ID used to retrieve OAuth2 token"
    },
    "client_secret": {
      "type": "string",
      "description": "client secret used to retrieve OAuth2 token"
    },
    "api_key": {
      "type": "string",
      "description": "key to identify API calling"
    },
    "redirect_uris": {
      "type": "array",
      "description": "List of registered redirect uris"
    },
    "client_name": {
      "type": "string",
      "description": "Application name"
    }
  },
  "required": [
    "client_id",
    "client_secret",
    "api_key",
    "client_name"
  ]
}

Application info
GET/oauth2/register/{client_id}

This resource is used to retrieve information about an application.

URI Parameters
HideShow
client_id
string (required) Example: 4224c721d0bf47a5a109250db484e0e8

Client id from the registration of the application

Renew OAuth secrets

POST /oauth2/register/4224c721d0bf47a5a109250db484e0e8/renewSecret
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "client_id": "4224c721d0bf47a5a109250db484e0e8",
  "client_secret": "5527f7a57202424f9ed5cc00e8b300fd",
  "api_key": "6667f7a57202424f9ed5cc00e8b666fd"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "client ID used to retrieve OAuth2 token"
    },
    "client_secret": {
      "type": "string",
      "description": "client secret used to retrieve OAuth2 token"
    },
    "api_key": {
      "type": "string",
      "description": "key to identify API calling"
    }
  },
  "required": [
    "client_id",
    "client_secret",
    "api_key"
  ]
}

Renew OAuth secrets
POST/oauth2/register/{client_id}/renewSecret

This resource is used to renew client secret used in OAuth2 for given client ID.

URI Parameters
HideShow
client_id
string (required) Example: 4224c721d0bf47a5a109250db484e0e8

Client id from the registration of the application

Delete application

DELETE /oauth2/register/4224c721d0bf47a5a109250db484e0e8
Responses200
This response has no content.

Delete application
DELETE/oauth2/register/{client_id}

This resource is used to delete application registration.

URI Parameters
HideShow
client_id
string (required) Example: 4224c721d0bf47a5a109250db484e0e8

Client id from the registration of the application

Token exchange resource

POST /oauth2/token
RequestsExchange code for access tokenExchange refresh token for access token
Body
{
  "grant_type": "authorization_code",
  "code": "123arjdmvcskfm",
  "redirect_uri": "https://myapp.example.com/handle_authentication",
  "client_id": "<your client ID>",
  "client_secret": "<your client secret>"
}
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "access_token": "aa225511dd",
  "expires_in": 7200,
  "refresh_token": "ff423123aa",
  "token_type": "bearer"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "access_token": {
      "type": "string",
      "description": "OAuth2 access token"
    },
    "expires_in": {
      "type": "number",
      "description": "token validity in seconds"
    },
    "refresh_token": {
      "type": "string",
      "description": "OAuth2 refresh token"
    },
    "token_type": {
      "type": "string",
      "description": "OAuth2 token type"
    }
  },
  "required": [
    "access_token",
    "expires_in",
    "token_type"
  ]
}
Body
{
  "grant_type": "refresh_token",
  "refresh_token": "123arjdmvcskfm",
  "client_id": "<your client ID>",
  "client_secret": "<your client secret>"
}
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "access_token": "aa225511dd",
  "expires_in": 7200,
  "refresh_token": "ff423123aa",
  "token_type": "bearer"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "access_token": {
      "type": "string",
      "description": "OAuth2 access token"
    },
    "expires_in": {
      "type": "number",
      "description": "token validity in seconds"
    },
    "refresh_token": {
      "type": "string",
      "description": "OAuth2 refresh token"
    },
    "token_type": {
      "type": "string",
      "description": "OAuth2 token type"
    }
  },
  "required": [
    "access_token",
    "expires_in",
    "token_type"
  ]
}

Token exchange resource
POST/oauth2/token

This resource is used to retrieve access token, either from authorization code or from refresh token.

Token revoke resource

POST /oauth2/token/revoke
Requestsexample 1
Headers
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Body
token=123arjdmvcskfm
Responses200
Body
___

Token revoke resource
POST/oauth2/token/revoke

This resource is used to revoke an access or refresh token. This operation is not supported by sandbox.

Profile

Resources handling information about current user. You need valid OAuth2 access token to access these resources.

User information

GET /openapi/bankingExtension/v0/profile
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "name": {
    "honourBeforeName": "Ing.",
    "honourAfterName": "PhD.",
    "firstName": "John",
    "middleNames": [
      "Peter",
      "Frank"
    ],
    "lastName": "Doe"
  },
  "salutation": "Mr.",
  "vocative": "John",
  "isAdult": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "object",
      "properties": {
        "honourBeforeName": {
          "type": "string",
          "description": "academical degree in front of name"
        },
        "honourAfterName": {
          "type": "string",
          "description": "academical degree behind name"
        },
        "firstName": {
          "type": "string",
          "description": "user first (given) name"
        },
        "middleNames": {
          "type": "array",
          "description": "middle names"
        },
        "lastName": {
          "type": "string",
          "description": "user family name"
        }
      },
      "required": [
        "firstName",
        "lastName"
      ]
    },
    "salutation": {
      "type": "string",
      "description": "salutation, e.g. Mr. or Mrs."
    },
    "vocative": {
      "type": "string",
      "description": "user's name vocative"
    },
    "isAdult": {
      "type": "boolean",
      "description": "set to true if user is over 18 years old"
    }
  },
  "required": [
    "name",
    "salutation",
    "isAdult"
  ]
}

Get user information
GET/openapi/bankingExtension/v0/profile

Get information about logged-in user.

User stories

“As developer, I want to greet users of my app.”

Cards

Resources to manipulate cards. You need valid OAuth2 access token to access these resources.

Single card detail

Resources for single payment card.

GET /openapi/bankingExtension/v0/cards/123
RequestsExisting card detailNon-Existing card detail
This response has no content.
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 12,
  "cardNumber": "516822******1234",
  "cardName": "John's main card",
  "cardStatus": "INACTIVE",
  "cardType": "DEBIT",
  "accountId": 123,
  "holderName": "John Doe",
  "validFrom": "2016-02",
  "validTo": "2022-02"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "internal card ID"
    },
    "cardNumber": {
      "type": "string",
      "description": "masked card number"
    },
    "cardName": {
      "type": "string",
      "description": "user description of card"
    },
    "cardStatus": {
      "type": "string",
      "enum": [
        "INACTIVE",
        "ACTIVE",
        "BLOCKED",
        "LOST",
        "STOLEN",
        "CANCELLED"
      ],
      "description": "card status"
    },
    "cardType": {
      "type": "string",
      "enum": [
        "DEBIT",
        "STICKER",
        "VIRTUAL"
      ]
    },
    "accountId": {
      "type": "number",
      "description": "ID of account that card belongs to"
    },
    "holderName": {
      "type": "string",
      "description": "card holder name"
    },
    "validFrom": {
      "type": "string",
      "description": "card valid from date"
    },
    "validTo": {
      "type": "string",
      "description": "card valid to date"
    }
  },
  "required": [
    "id",
    "cardNumber",
    "cardName",
    "cardStatus",
    "cardType",
    "accountId",
    "holderName",
    "validFrom",
    "validTo"
  ]
}
This response has no content.
Responses404

When card is not found.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Get card details
GET/openapi/bankingExtension/v0/cards/{id}

Retrieve details about specified payment card. User can only see details of cards belonging to account that he owns.

URI Parameters
HideShow
id
number (required) Example: 123

internal payment card identifier

Card limits

GET /openapi/bankingExtension/v0/cards/12/limits
RequestsExisting card detailNon-existing card limits
This response has no content.
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "weeklyPosLimit": 10000,
  "weeklyPosRemaining": 9800,
  "weeklyAtmLimit": 100000,
  "weeklyAtmRemaining": 50000,
  "weeklyInternetLimit": 5000,
  "weeklyInternetRemaining": 5000,
  "dailyContactlessLimit": 2000
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "weeklyPosLimit": {
      "type": "number",
      "description": "weekly limit of payments at marchant terminals"
    },
    "weeklyPosRemaining": {
      "type": "number",
      "description": "remaining limit of payments at merchant terminals"
    },
    "weeklyAtmLimit": {
      "type": "number",
      "description": "weekly limit of ATM withdrawals"
    },
    "weeklyAtmRemaining": {
      "type": "number",
      "description": "remaining limit of ATM withdrawals"
    },
    "weeklyInternetLimit": {
      "type": "number",
      "description": "weekly limit of payments over internet"
    },
    "weeklyInternetRemaining": {
      "type": "number",
      "description": "remaining limit of payments over internet"
    },
    "dailyContactlessLimit": {
      "type": "number",
      "description": "daily limit for contactless payments"
    }
  }
}
This response has no content.
Responses404

When card is not found.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Card limits
GET/openapi/bankingExtension/v0/cards/{cardId}/limits

Retrieve card currently set limits (whether permanent or temporary).

URI Parameters
HideShow
cardId
string (required) Example: 12

internal payment card identifier

Cards list

GET /openapi/bankingExtension/v0/cards
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "data": [
    {
      "id": 12,
      "cardNumber": "516822******1234",
      "cardName": "John's main card",
      "cardStatus": "INACTIVE",
      "cardType": "DEBIT",
      "accountId": 123,
      "holderName": "John Doe",
      "validFrom": "2016-02",
      "validTo": "2022-02"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "internal card ID"
          },
          "cardNumber": {
            "type": "string",
            "description": "masked card number"
          },
          "cardName": {
            "type": "string",
            "description": "user description of card"
          },
          "cardStatus": {
            "type": "string",
            "enum": [
              "INACTIVE",
              "ACTIVE",
              "BLOCKED",
              "LOST",
              "STOLEN",
              "CANCELLED"
            ],
            "description": "card status"
          },
          "cardType": {
            "type": "string",
            "enum": [
              "DEBIT",
              "STICKER",
              "VIRTUAL"
            ]
          },
          "accountId": {
            "type": "number",
            "description": "ID of account that card belongs to"
          },
          "holderName": {
            "type": "string",
            "description": "card holder name"
          },
          "validFrom": {
            "type": "string",
            "description": "card valid from date"
          },
          "validTo": {
            "type": "string",
            "description": "card valid to date"
          }
        },
        "required": [
          "id",
          "cardNumber",
          "cardName",
          "cardStatus",
          "cardType",
          "accountId",
          "holderName",
          "validFrom",
          "validTo"
        ]
      }
    }
  },
  "required": [
    "data"
  ]
}

Get list of payment cards
GET/openapi/bankingExtension/v0/cards

Get a list of payment cards for logged-in user. Only show cards belonging to accounts that are owned by user. Only active, blocked by user, lost, stolen and retained cards are retrieved.

User stories

“As developer, I want to offer my users overview of their products.”

feature supported by resource
paging no
sorting no
filtering no

Cards by account

GET /openapi/bankingExtension/v0/accounts/123/cards
RequestsExisting accountNon-existing account
This response has no content.
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "data": [
    {
      "id": 12,
      "cardNumber": "516822******1234",
      "cardName": "John's main card",
      "cardStatus": "INACTIVE",
      "cardType": "DEBIT",
      "accountId": 123,
      "holderName": "John Doe",
      "validFrom": "2016-02",
      "validTo": "2022-02"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "internal card ID"
          },
          "cardNumber": {
            "type": "string",
            "description": "masked card number"
          },
          "cardName": {
            "type": "string",
            "description": "user description of card"
          },
          "cardStatus": {
            "type": "string",
            "enum": [
              "INACTIVE",
              "ACTIVE",
              "BLOCKED",
              "LOST",
              "STOLEN",
              "CANCELLED"
            ],
            "description": "card status"
          },
          "cardType": {
            "type": "string",
            "enum": [
              "DEBIT",
              "STICKER",
              "VIRTUAL"
            ]
          },
          "accountId": {
            "type": "number",
            "description": "ID of account that card belongs to"
          },
          "holderName": {
            "type": "string",
            "description": "card holder name"
          },
          "validFrom": {
            "type": "string",
            "description": "card valid from date"
          },
          "validTo": {
            "type": "string",
            "description": "card valid to date"
          }
        },
        "required": [
          "id",
          "cardNumber",
          "cardName",
          "cardStatus",
          "cardType",
          "accountId",
          "holderName",
          "validFrom",
          "validTo"
        ]
      }
    }
  },
  "required": [
    "data"
  ]
}
This response has no content.
Responses404

When account is not found.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Get list of cards belonging to account
GET/openapi/bankingExtension/v0/accounts/{accountId}/cards

Get payment cards of given account. Only active, blocked by user and stolen cards are retrieved.

This resource returns actual state of limits. If temporary limits are set, this resource returns their values instead of “regular” limits.

feature supported by resource
paging no
sorting no
filtering no
URI Parameters
HideShow
accountId
number (required) Example: 123

internal account identifier

Transactions

Resources to get transaction history. You need valid OAuth2 access token to access these resources.

Single transaction

— this section will be deleted after MSON support reaches its maturity —

Additional info by transaction type:

TransactionInfoDomestic

Domestic transaction.

attribute name example value attribute type description
constantSymbol 0558 (string, optional) constant symbol
variableSymbol 9 (string, optional) variable symbol
specificSymbol 100011 (string, optional) specific symbol

TransactionInfoCard

Card transaction.

attribute name example value attribute type description
mcc 3081 (string, optional) Merchant Category Code
merchantName SomeCompany, Ltd. (string, optional) merchant name
cardNumber 34xx-xxxx-xxxx-6289 (string, required) masked card number used for transaction

TransactionInfoForeign

Transaction to/from abroad.

attribute name example value attribute type description
originalValue {“amount”: 30.50, “currency”: “USD”} (Money, optional) value of transaction in original currency
exchangeRate 12.80 (number, optional) exchange rate valid at the time of transfer
PUT /opanapi/bankingExtension/v0/transactions/123
RequestsUpdate transaction descriptionUpdate non-existing transaction description
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "userDescription": "gift to Michaela"
}
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": "123_12345",
  "accountId": 123,
  "value": {
    "amount": 1000.6,
    "currency": "CZK"
  },
  "partyAccount": {
    "prefix": "000000",
    "accountNumber": "1235335010",
    "bankCode": "3030"
  },
  "partyDescription": "John Doe",
  "direction": "INCOMING",
  "transactionType": "PAYMENT_HOME",
  "valueDate": "2016-02-10T10:00Z",
  "bookingDate": "2016-02-09T10:00Z",
  "userDescription": "gift to Michaela",
  "payerMessage": "need to pay this",
  "payeeMessage": "Hello, world!",
  "categoryId": 1,
  "transactionFee": 25,
  "transactionFeeCanceled": false,
  "additionalInfoDomestic": {
    "constantSymbol": "0558",
    "variableSymbol": "9",
    "specificSymbol": "100011"
  },
  "additionalInfoForeign": {
    "originalValue": {
      "amount": 1000.6,
      "currency": "CZK"
    },
    "exchangeRate": 12.8
  },
  "additionalInfoCard": {
    "mcc": "3081",
    "merchantName": "SomeCompany, Ltd.",
    "cardNumber": "34xx-xxxx-xxxx-6289"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "internal transaction identified"
    },
    "accountId": {
      "type": "number",
      "description": "account to that transaction belongs (to which it is accounted)"
    },
    "value": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "description": "amount of money"
        },
        "currency": {
          "type": "string",
          "description": "currency of money"
        }
      },
      "required": [
        "amount",
        "currency"
      ],
      "description": "amount & currency used for bookkeeping (e.g. amount in account's currency). Can be negative e.g. if something was withdrawn from an account. Original transaction amount and currency will be specified in `additionalInfo` object if applicable"
    },
    "partyAccount": {
      "type": "object",
      "properties": {
        "prefix": {
          "type": "string",
          "description": "account number prefix"
        },
        "accountNumber": {
          "type": "string",
          "description": "account number. For domestic accounts, this will be specified in national format."
        },
        "bankCode": {
          "type": "string",
          "description": "for domestic accounts, bank code in national format; for foreign accounts, BIC code."
        }
      },
      "required": [
        "accountNumber",
        "bankCode"
      ],
      "description": "party account number"
    },
    "partyDescription": {
      "type": "string",
      "description": "party description"
    },
    "direction": {
      "type": "string",
      "enum": [
        "INCOMING",
        "OUTGOING",
        "BOTH"
      ],
      "description": "transaction direction"
    },
    "transactionType": {
      "type": "string",
      "enum": [
        "PAYMENT_HOME",
        "PAYMENT_ABROAD",
        "PAYMENT_PERSONAL",
        "PAYMENT_ACCOUNT",
        "STANDING_ORDER",
        "SAVING",
        "DIRECT_DEBIT",
        "DIRECT_DEBIT_SIPO",
        "CARD",
        "CASH",
        "FEE",
        "TAX",
        "INTEREST",
        "INSURANCE",
        "LOAN",
        "MORTGAGE",
        "SAZKA",
        "OTHER",
        "BLOCKING"
      ],
      "description": "transaction type"
    },
    "valueDate": {
      "type": "string",
      "description": "transaction value date, e.g. the day transaction \"happened\""
    },
    "bookingDate": {
      "type": "string",
      "description": "transaction booking date, e.g. the day transaction was bookkeeped"
    },
    "userDescription": {
      "type": "string",
      "description": "user transaction description"
    },
    "payerMessage": {
      "type": "string",
      "description": "message for payer. Empty for incoming transacionts."
    },
    "payeeMessage": {
      "type": "string",
      "description": "message for payee (e.g. for client receiving transaction)"
    },
    "categoryId": {
      "type": "number",
      "description": "id of category for transaction. More info about category can be retrieved using /openapi/banking/categories resource."
    },
    "transactionFee": {
      "type": "number",
      "description": "fee related to transaction, in account's currency"
    },
    "transactionFeeCanceled": {
      "type": "boolean",
      "description": "set to true if transaction fee is canceled."
    },
    "additionalInfoDomestic": {
      "type": "object",
      "properties": {
        "constantSymbol": {
          "type": "string"
        },
        "variableSymbol": {
          "type": "string"
        },
        "specificSymbol": {
          "type": "string"
        }
      },
      "description": "domestic payments additional info (symbols for fomestic payments)"
    },
    "additionalInfoForeign": {
      "type": "object",
      "properties": {
        "originalValue": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number",
              "description": "amount of money"
            },
            "currency": {
              "type": "string",
              "description": "currency of money"
            }
          },
          "required": [
            "amount",
            "currency"
          ],
          "description": "amount & currency in which transaction was originated"
        },
        "exchangeRate": {
          "type": "number",
          "description": "exchange rate valid at the time of transfer"
        }
      },
      "description": "foreign payments additional info (original value and exchange rate)"
    },
    "additionalInfoCard": {
      "type": "object",
      "properties": {
        "mcc": {
          "type": "string",
          "description": "Merchant Category code"
        },
        "merchantName": {
          "type": "string"
        },
        "cardNumber": {
          "type": "string",
          "description": "masked card number used for transaction"
        }
      },
      "required": [
        "cardNumber"
      ],
      "description": "card payemnts additional info (card number, mcc and merchant name)"
    }
  },
  "required": [
    "id",
    "accountId",
    "value",
    "direction",
    "transactionType",
    "valueDate",
    "bookingDate"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "userDescription": "gift to Michaela"
}
Responses404

When transaction is not found.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Change transaction description
PUT/opanapi/bankingExtension/v0/transactions/{id}

Change transaction description. Only userDescription attribute can be modified, other attributes are ignored.

Note: maximum length of userDescription is 140 characters

User stories

“As developer, I want to offer my users a way how to identify current transaction.”

URI Parameters
HideShow
id
string (required) Example: 123

internal transaction identifier

Categories

Resources used for retrieving categorization information.

GET /openapi/bankingExtension/v0/categories?type=BANK&active_only=true
RequestsBank categoriesBad parameter value
This response has no content.
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "data": [
    {
      "id": 12,
      "name": "Food",
      "type": "BANK",
      "active": true
    }
  ],
  "pagingInfo": {
    "itemsPerPage": 10,
    "nextPage": "transactions?sort=category&limit=10&after=25",
    "prevPage": "transactions?sort=category&limit=10&before=25"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "internal category ID"
          },
          "name": {
            "type": "string",
            "description": "human readable category name"
          },
          "type": {
            "type": "string",
            "enum": [
              "BANK",
              "USER"
            ],
            "description": "category type"
          },
          "active": {
            "type": "boolean",
            "description": "whether the category can be used for categorisation (true) or is only provided for back reference (false)"
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "active"
        ]
      }
    },
    "pagingInfo": {
      "type": "object",
      "properties": {
        "itemsPerPage": {
          "type": "number",
          "description": "number of items per page"
        },
        "nextPage": {
          "type": "string",
          "description": "request to retrieve next page. Either nextPage or previousPage is returned, depending whether you specify after or before parameter (or none, if you retrieve whole collection)."
        },
        "prevPage": {
          "type": "string",
          "description": "request to retrieve previous page."
        }
      },
      "required": [
        "itemsPerPage"
      ]
    }
  },
  "required": [
    "data"
  ]
}
This response has no content.
Responses400

When bad parameter value is specified.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Categories for user and/or bank
GET/openapi/bankingExtension/v0/categories{?type,active_only}

Retrieve all categories defined for logged-in user. Alternatively, you can retrieve only bank-defined categories by specifying type=BANK attribute.

feature supported by resource
paging yes
sorting no
filtering no

This resource supports paging. As a value to before and after parameters, use id attribute.

User stories

“As developer, I want to sort transactions according to categories to provide spending overview”

URI Parameters
HideShow
type
string (optional) Example: BANK

Category type. If set to “BANK”, only bank-defined categories are retrieved. If set to “USER”, only user categories are retrieved. If not specified, categories are returned according to user setting in Internet Banking. Any other value returns error (400 Bad Request)

Choices: BANK USER

active_only
boolean (optional) Default: true Example: true

If set to true (default), only categories that can be used for new transaction categorisation are retrieved. If set to false, both active categories and categories that has been inactivated will be retrieved (usefull for category back reference)

Withdrawal codes

Resources for handling withdrawal codes. You need valid OAuth2 access token to access these resources.

Withdrawal code

GET /openapi/bankingExtension/v0/withdrawalcodes/138294
RequestsExisting codeNon-existing code
This response has no content.
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 312,
  "accountId": 12,
  "status": "ACTIVE",
  "value": {
    "amount": 1000.6,
    "currency": "CZK"
  },
  "expirationDate": "2016-02-15T15:20:00Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "internal withdrawal code ID"
    },
    "accountId": {
      "type": "number",
      "description": "account ID this code belongs to"
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "EXPIRED",
        "CANCELLED",
        "USED"
      ],
      "description": "withdrawal code status"
    },
    "value": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "description": "amount of money"
        },
        "currency": {
          "type": "string",
          "description": "currency of money"
        }
      },
      "required": [
        "amount",
        "currency"
      ],
      "description": "amount of money that this code authorizes to withdraw"
    },
    "expirationDate": {
      "type": "string",
      "description": "withdrawal code expiration date"
    }
  },
  "required": [
    "id",
    "accountId",
    "status",
    "value"
  ]
}
This response has no content.
Responses404

Specified withdrawal code is not found.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Withdrawal code detail
GET/openapi/bankingExtension/v0/withdrawalcodes/{id}

Get details about specified withdrawal code.

URI Parameters
HideShow
id
number (required) Example: 138294

ID of withdrawal code

DELETE /openapi/bankingExtension/v0/withdrawalcodes/138294
RequestsActive codeInactive codeNon-Existing code
This response has no content.
Responses204

Withdrawal code has been invalidated successfully.

Headers
Content-Type: application/json;charset=UTF-8
This response has no content.
Responses422

Withdrawal code can not be invalidated (e.g. code is not in ACTIVE state)

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}
This response has no content.
Responses404

Specified withdrawal code is not found.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Invalidate withdrawal code
DELETE/openapi/bankingExtension/v0/withdrawalcodes/{id}

Invalidate specified withdrawal code. Only active withdrawal codes can be invalidated.

URI Parameters
HideShow
id
number (required) Example: 138294

ID of withdrawal code

Withdrawal code resend

POST /openapi/bankingExtension/v0/withdrawalcodes/231/resend
RequestsActive codeInactive codeNon-existing code
This response has no content.
Responses201

Withdrawal code has been sent successfully.

Headers
Content-Type: application/json;charset=UTF-8
This response has no content.
Responses422

Withdrawal code can not be resend (e.g. code is not in ACTIVE state or max. number of resends was reached)

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}
This response has no content.
Responses404

Specified withdrawal code is not found.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Resend active withdrawal code
POST/openapi/bankingExtension/v0/withdrawalcodes/{id}/resend

Call this resource to re-send active withdrawal code via SMS to user’s primary phone number. Only active, authorized codes can be resent.

Note: number of re-send attempts is limited (currently to 3 attempts), additional calls to this resource have no effect.

URI Parameters
HideShow
id
number (required) Example: 231

ID of withdrawal code

Withdrawal codes collection

GET /openapi/bankingExtension/v0/withdrawalcodes?active_only=false
RequestsActive and inactive codes
This response has no content.
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "data": [
    {
      "id": 312,
      "accountId": 12,
      "status": "ACTIVE",
      "value": {
        "amount": 1000.6,
        "currency": "CZK"
      },
      "expirationDate": "2016-02-15T15:20:00Z"
    }
  ],
  "pagingInfo": {
    "itemsPerPage": 10,
    "nextPage": "transactions?sort=category&limit=10&after=25",
    "prevPage": "transactions?sort=category&limit=10&before=25"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "internal withdrawal code ID"
          },
          "accountId": {
            "type": "number",
            "description": "account ID this code belongs to"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "EXPIRED",
              "CANCELLED",
              "USED"
            ],
            "description": "withdrawal code status"
          },
          "value": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "number",
                "description": "amount of money"
              },
              "currency": {
                "type": "string",
                "description": "currency of money"
              }
            },
            "required": [
              "amount",
              "currency"
            ],
            "description": "amount of money that this code authorizes to withdraw"
          },
          "expirationDate": {
            "type": "string",
            "description": "withdrawal code expiration date"
          }
        },
        "required": [
          "id",
          "accountId",
          "status",
          "value"
        ]
      }
    },
    "pagingInfo": {
      "type": "object",
      "properties": {
        "itemsPerPage": {
          "type": "number",
          "description": "number of items per page"
        },
        "nextPage": {
          "type": "string",
          "description": "request to retrieve next page. Either nextPage or previousPage is returned, depending whether you specify after or before parameter (or none, if you retrieve whole collection)."
        },
        "prevPage": {
          "type": "string",
          "description": "request to retrieve previous page."
        }
      },
      "required": [
        "itemsPerPage"
      ]
    }
  },
  "required": [
    "data"
  ]
}

List of issued withdrawal codes
GET/openapi/bankingExtension/v0/withdrawalcodes{?active_only}

Get a list of issued withdrawal codes for logged-in user. User can only see withdrawal codes to accounts that he owns.

feature supported by resource
paging yes
sorting no
filtering no

This resource supports paging. As a value to before and after parameters, use id attribute.

Note: there can be only one ACTIVE withdrawal code per given user and account.

User stories

“As app developer, I want my to inform my users about withdrawal codes usage history.”

URI Parameters
HideShow
active_only
boolean (optional) Default: true Example: false

if set to false, resource will include already used or invalidated withdrawal codes. By default, only it returns only active codes.

Withdrawal code generation

POST /openapi/bankingExtension/v0/accounts/231/withdrawalcodes
RequestsValid requestInvalid request - bad amountNon-existing account
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "amountInCZK": 1000,
  "override": [
    "ERR_PAY_1244_INSUFFICIENT_FUNDS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "amountInCZK": {
      "type": "number",
      "description": "value of withdrawal code, in CZK currency."
    },
    "override": {
      "type": "array",
      "description": "list of warnings that should be ignored"
    }
  },
  "required": [
    "amountInCZK"
  ]
}
Responses200

Withdrawal code is prepared to be authorized.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "authorization": {
    "authorizationId": "aobrCdeU1Yu4HG_sKQe_uP25B0CYz7hsPYK_w9uF41ZK90KE9mANj_",
    "authResultURL": "/openapi/banking/withdrawalcodes/authorization/aobrCdeU1Yu4HG_sKQe_uP25B0",
    "mustRedirect": false,
    "redirectURL": "https://www.airbank.cz/authorization/aobrCdeU1Yu4HG_sKQe_uP25B0",
    "status": "IN_PROGRESS"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "authorization": {
      "type": "object",
      "properties": {
        "authorizationId": {
          "type": "string",
          "description": "internal authorization request identifier. Expect arbitrary long string."
        },
        "authResultURL": {
          "type": "string",
          "description": "resource used to GET authorization result"
        },
        "mustRedirect": {
          "type": "boolean",
          "description": "if set to true, application must redirect user to `redirectURL` to complete authorization"
        },
        "redirectURL": {
          "type": "string",
          "description": "redirect URL for fallback authorization or for redirecting if `mustRedirect` is set to true"
        },
        "status": {
          "type": "string",
          "enum": [
            "IN_PROGRESS",
            "AUTHORIZED",
            "REJECTED",
            "TIMEOUTED"
          ]
        }
      },
      "required": [
        "authorizationId",
        "authResultURL",
        "mustRedirect",
        "redirectURL",
        "status"
      ]
    }
  },
  "required": [
    "authorization"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "amountInCZK": 123
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "amountInCZK": {
      "type": "number",
      "description": "value of withdrawal code, in account's currency."
    }
  },
  "required": [
    "amountInCZK"
  ]
}
Responses400

There are validation errors.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "amountInCZK": 1000
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "amountInCZK": {
      "type": "number",
      "description": "value of withdrawal code, in account's currency."
    }
  },
  "required": [
    "amountInCZK"
  ]
}
Responses404

Account does not exists.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Generate withdrawal code
POST/openapi/bankingExtension/v0/accounts/{accountId}/withdrawalcodes

Generate new withdrawal code for specified account. Users can only generate withdrawal codes to accounts that they own.

You can only generate withdrawal code for certain amounts, use resource /openapi/banking/accounts/{accountId}/withdrawalcodes/amounts to get possible values.

This resource requires authorization

This resource initiates withdrawal code creation, but this operation needs an additional authorization before the code can be retrieved. Use resource Fetch authorized withdrawal code to get authorization result and generated code value.

URI Parameters
HideShow
accountId
number (required) Example: 231

account ID to generate withdrawal code on.

Withdrawal code authorization

GET /openapi/bankingExtension/v0/withdrawalcodes/authorization/231
RequestsExisting authorizationNon-Existing authorization
This response has no content.
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "withdrawalCode": {
    "id": 312,
    "accountId": 12,
    "status": "ACTIVE",
    "value": {
      "amount": 1000.6,
      "currency": "CZK"
    },
    "expirationDate": "2016-02-15T15:20:00Z",
    "code": 444608
  },
  "authorizationResult": {
    "authorizationId": "aobrCdeU1Yu4HG_sKQe_uP25B0CYz7hsPYK_w9uF41ZK90KE9mANj_",
    "status": "IN_PROGRESS"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "withdrawalCode": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "internal withdrawal code ID"
        },
        "accountId": {
          "type": "number",
          "description": "account ID this code belongs to"
        },
        "status": {
          "type": "string",
          "enum": [
            "ACTIVE",
            "EXPIRED",
            "CANCELLED",
            "USED"
          ],
          "description": "withdrawal code status"
        },
        "value": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number",
              "description": "amount of money"
            },
            "currency": {
              "type": "string",
              "description": "currency of money"
            }
          },
          "required": [
            "amount",
            "currency"
          ],
          "description": "amount of money that this code authorizes to withdraw"
        },
        "expirationDate": {
          "type": "string",
          "description": "withdrawal code expiration date"
        },
        "code": {
          "type": "number",
          "description": "generated withdrawal code"
        }
      },
      "required": [
        "id",
        "accountId",
        "status",
        "value",
        "code"
      ]
    },
    "authorizationResult": {
      "type": "object",
      "properties": {
        "authorizationId": {
          "type": "string",
          "description": "internal authorization request identifier. Expect arbitrary long string."
        },
        "status": {
          "type": "string",
          "enum": [
            "IN_PROGRESS",
            "AUTHORIZED",
            "REJECTED",
            "TIMEOUTED"
          ]
        }
      },
      "required": [
        "authorizationId",
        "status"
      ]
    }
  },
  "required": [
    "authorizationResult"
  ]
}
This response has no content.
Responses404

Specified authorization request does not exist.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Fetch authorized withdrawal code
GET/openapi/bankingExtension/v0/withdrawalcodes/authorization/{id}

This resource is used to grab result of authorization for withdrawal code. When authorization is successfull, it also returns authorized withdrawal code.

For security reasons, there is no other resource to retrieve actual code value.

Authorized code is valid for limited amount of time (currently 12 hours, but this might be changed).

URI Parameters
HideShow
id
number (required) Example: 231

authorization request ID.

Possible withdrawal code amounts

GET /openapi/bankingExtension/v0/accounts/50704580/withdrawalcodes/amounts
Responses200

Possible withdrawal code values on given account.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "amountsInCZK": [
    100,
    200,
    300
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "amountsInCZK": {
      "type": "array",
      "description": "possible withdrawal code amounts in CZK currency."
    }
  },
  "required": [
    "amountsInCZK"
  ]
}

Retrieve possible amounts for withdrawal code
GET/openapi/bankingExtension/v0/accounts/{accountId}/withdrawalcodes/amounts

This resource provides possible withdrawal code amounts, reflecting currently available balance and remaining limits.

URI Parameters
HideShow
accountId
number (required) Example: 50704580

account ID to generate withdrawal code on.

Payments

Domestic payment order resources. You need valid OAuth2 access token to access these resources.

Specific domestic payment order

PUT /openapi/bankingExtension/v0/payments/domestic/123
RequestsUpdate existing payment orderUpdate non-existing payment orderInvalid update request
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "value": {
    "amount": 1000.6,
    "currency": "CZK"
  },
  "partyAccount": {
    "prefix": "000000",
    "accountNumber": "1235335010",
    "bankCode": "3030"
  },
  "dueDate": "2018-01-22",
  "payeeMessage": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "payerMessage": "Mauris mollis justo neque, ac iaculis erat lacinia vel.",
  "categoryId": 1,
  "additionalInfo": {
    "constantSymbol": "0558",
    "variableSymbol": "9",
    "specificSymbol": "100011"
  },
  "sendConfirmationEmail": true,
  "override": [
    "WRN_INSUFFICIENT_FUNDS"
  ],
  "accountId": 50973220
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "value": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "description": "amount of money"
        },
        "currency": {
          "type": "string",
          "description": "currency of money"
        }
      },
      "required": [
        "amount",
        "currency"
      ],
      "description": "amount & currency of payment order"
    },
    "partyAccount": {
      "type": "object",
      "properties": {
        "prefix": {
          "type": "string",
          "description": "account number prefix"
        },
        "accountNumber": {
          "type": "string",
          "description": "account number. For domestic accounts, this will be specified in national format."
        },
        "bankCode": {
          "type": "string",
          "description": "for domestic accounts, bank code in national format; for foreign accounts, BIC code."
        }
      },
      "required": [
        "accountNumber",
        "bankCode"
      ],
      "description": "party account number"
    },
    "dueDate": {
      "type": "string",
      "description": "payment order due date"
    },
    "payeeMessage": {
      "type": "string",
      "description": "message for payee"
    },
    "payerMessage": {
      "type": "string",
      "description": "message for payer"
    },
    "categoryId": {
      "type": "number",
      "description": "id of category for payment order. More info about category can be retrieved using /openapi/banking/categories resource."
    },
    "additionalInfo": {
      "type": "object",
      "properties": {
        "constantSymbol": {
          "type": "string"
        },
        "variableSymbol": {
          "type": "string"
        },
        "specificSymbol": {
          "type": "string"
        }
      },
      "description": "payment order additional info (symbols)"
    },
    "sendConfirmationEmail": {
      "type": "boolean",
      "description": "whether confirmation e-mail should be sent at payment's realization"
    },
    "override": {
      "type": "array",
      "description": "list of warnings that should be ignored"
    },
    "accountId": {
      "type": "number",
      "description": "account to that payment belongs (to which it is accounted)"
    }
  },
  "required": [
    "value",
    "partyAccount",
    "dueDate",
    "accountId"
  ]
}
Responses200

Payment order update request was successfull, additional authorization is required.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "authorization": {
    "authorizationId": "aobrCdeU1Yu4HG_sKQe_uP25B0CYz7hsPYK_w9uF41ZK90KE9mANj_",
    "authResultURL": "/openapi/banking/payments/domestic/authorization/aobrCdeU1Yu4HG_sKQe_uP25B0",
    "mustRedirect": false,
    "redirectURL": "https://www.airbank.cz/authorization/aobrCdeU1Yu4HG_sKQe_uP25B0",
    "status": "IN_PROGRESS"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "authorization": {
      "type": "object",
      "properties": {
        "authorizationId": {
          "type": "string",
          "description": "internal authorization request identifier. Expect arbitrary long string."
        },
        "authResultURL": {
          "type": "string",
          "description": "resource used to GET authorization result"
        },
        "mustRedirect": {
          "type": "boolean",
          "description": "if set to true, application must redirect user to `redirectURL` to complete authorization"
        },
        "redirectURL": {
          "type": "string",
          "description": "redirect URL for fallback authorization or for redirecting if `mustRedirect` is set to true"
        },
        "status": {
          "type": "string",
          "enum": [
            "IN_PROGRESS",
            "AUTHORIZED",
            "REJECTED",
            "TIMEOUTED"
          ]
        }
      },
      "required": [
        "authorizationId",
        "authResultURL",
        "mustRedirect",
        "redirectURL",
        "status"
      ]
    }
  },
  "required": [
    "authorization"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "value": {
    "amount": 1000.6,
    "currency": "CZK"
  },
  "partyAccount": {
    "prefix": "000000",
    "accountNumber": "1235335010",
    "bankCode": "3030"
  },
  "dueDate": "2018-01-22",
  "payeeMessage": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "payerMessage": "Mauris mollis justo neque, ac iaculis erat lacinia vel.",
  "categoryId": 1,
  "additionalInfo": {
    "constantSymbol": "0558",
    "variableSymbol": "9",
    "specificSymbol": "100011"
  },
  "sendConfirmationEmail": true,
  "override": [
    "WRN_INSUFFICIENT_FUNDS"
  ],
  "accountId": 50973220
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "value": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "description": "amount of money"
        },
        "currency": {
          "type": "string",
          "description": "currency of money"
        }
      },
      "required": [
        "amount",
        "currency"
      ],
      "description": "amount & currency of payment order"
    },
    "partyAccount": {
      "type": "object",
      "properties": {
        "prefix": {
          "type": "string",
          "description": "account number prefix"
        },
        "accountNumber": {
          "type": "string",
          "description": "account number. For domestic accounts, this will be specified in national format."
        },
        "bankCode": {
          "type": "string",
          "description": "for domestic accounts, bank code in national format; for foreign accounts, BIC code."
        }
      },
      "required": [
        "accountNumber",
        "bankCode"
      ],
      "description": "party account number"
    },
    "dueDate": {
      "type": "string",
      "description": "payment order due date"
    },
    "payeeMessage": {
      "type": "string",
      "description": "message for payee"
    },
    "payerMessage": {
      "type": "string",
      "description": "message for payer"
    },
    "categoryId": {
      "type": "number",
      "description": "id of category for payment order. More info about category can be retrieved using /openapi/banking/categories resource."
    },
    "additionalInfo": {
      "type": "object",
      "properties": {
        "constantSymbol": {
          "type": "string"
        },
        "variableSymbol": {
          "type": "string"
        },
        "specificSymbol": {
          "type": "string"
        }
      },
      "description": "payment order additional info (symbols)"
    },
    "sendConfirmationEmail": {
      "type": "boolean",
      "description": "whether confirmation e-mail should be sent at payment's realization"
    },
    "override": {
      "type": "array",
      "description": "list of warnings that should be ignored"
    },
    "accountId": {
      "type": "number",
      "description": "account to that payment belongs (to which it is accounted)"
    }
  },
  "required": [
    "value",
    "partyAccount",
    "dueDate",
    "accountId"
  ]
}
Responses404

Payment order not found.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "value": {
    "amount": 1000.6,
    "currency": "CZK"
  },
  "partyAccount": {
    "prefix": "000000",
    "accountNumber": "111111111",
    "bankCode": "3030"
  },
  "dueDate": "2010-01-22",
  "payeeMessage": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "payerMessage": "Mauris mollis justo neque, ac iaculis erat lacinia vel.",
  "additionalInfo": {
    "constantSymbol": "0558",
    "variableSymbol": "9",
    "specificSymbol": "100011"
  },
  "accountId": 50973220
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "value": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "description": "amount of money"
        },
        "currency": {
          "type": "string",
          "description": "currency of money"
        }
      },
      "required": [
        "amount",
        "currency"
      ],
      "description": "amount & currency of payment order"
    },
    "partyAccount": {
      "type": "object",
      "properties": {
        "prefix": {
          "type": "string",
          "description": "account number prefix"
        },
        "accountNumber": {
          "type": "string",
          "description": "invalid account number (mod 11)"
        },
        "bankCode": {
          "type": "string",
          "description": "for domestic accounts, bank code in national format; for foreign accounts, BIC code."
        }
      },
      "required": [
        "accountNumber",
        "bankCode"
      ],
      "description": "party account number"
    },
    "dueDate": {
      "type": "string",
      "description": "payment order due date"
    },
    "payeeMessage": {
      "type": "string",
      "description": "message for payee"
    },
    "payerMessage": {
      "type": "string",
      "description": "message for payer"
    },
    "categoryId": {
      "type": "number",
      "description": "id of category for payment order. More info about category can be retrieved using /openapi/banking/categories resource."
    },
    "additionalInfo": {
      "type": "object",
      "properties": {
        "constantSymbol": {
          "type": "string"
        },
        "variableSymbol": {
          "type": "string"
        },
        "specificSymbol": {
          "type": "string"
        }
      },
      "description": "payment order additional info (symbols)"
    },
    "accountId": {
      "type": "number",
      "description": "account to that payment belongs (to which it is accounted)"
    }
  },
  "required": [
    "value",
    "partyAccount",
    "dueDate",
    "accountId"
  ]
}
Responses422

There are validation errors (specified in response body). You can override errors with WARN severity by specifying their codes in override request attribute.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Update a specific domestic payment order
PUT/openapi/bankingExtension/v0/payments/domestic/{id}

Update a specific domestic payment order. Only payment orders with userEditable attribute set to true can be edited.

This resource requires authorization, e.g. payment order is not updated unless authorized by user - see section Authorization.

URI Parameters
HideShow
id
number (required) Example: 123

Specific domestic payment order identifier.

DELETE /openapi/bankingExtension/v0/payments/domestic/123
RequestsAuthorization requiredAuthorization not requiredNon-existing payment order
This response has no content.
Responses200

Payment order deletion requires authorization.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "authorization": {
    "authorizationId": "aobrCdeU1Yu4HG_sKQe_uP25B0CYz7hsPYK_w9uF41ZK90KE9mANj_",
    "authResultURL": "/openapi/banking/payments/domestic/authorization/aobrCdeU1Yu4HG_sKQe_uP25B0",
    "mustRedirect": false,
    "redirectURL": "https://www.airbank.cz/authorization/aobrCdeU1Yu4HG_sKQe_uP25B0",
    "status": "IN_PROGRESS"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "authorization": {
      "type": "object",
      "properties": {
        "authorizationId": {
          "type": "string",
          "description": "internal authorization request identifier. Expect arbitrary long string."
        },
        "authResultURL": {
          "type": "string",
          "description": "resource used to GET authorization result"
        },
        "mustRedirect": {
          "type": "boolean",
          "description": "if set to true, application must redirect user to `redirectURL` to complete authorization"
        },
        "redirectURL": {
          "type": "string",
          "description": "redirect URL for fallback authorization or for redirecting if `mustRedirect` is set to true"
        },
        "status": {
          "type": "string",
          "enum": [
            "IN_PROGRESS",
            "AUTHORIZED",
            "REJECTED",
            "TIMEOUTED"
          ]
        }
      },
      "required": [
        "authorizationId",
        "authResultURL",
        "mustRedirect",
        "redirectURL",
        "status"
      ]
    }
  },
  "required": [
    "authorization"
  ]
}
This response has no content.
Responses204

Payment order was deleted.

Headers
Content-Type: application/json;charset=UTF-8
This response has no content.
Responses404

Specific domestic payment order not found.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "code": "ERR_1000_SOME_ERROR_CODE",
      "message": "Some error/validation message description",
      "severity": "ERROR",
      "attribute": "accountId",
      "ticketId": "UAT1:AMS:20160516-091658.450:45e4"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "unique internal error code"
          },
          "message": {
            "type": "string",
            "description": "human readable error description (non-localized)"
          },
          "severity": {
            "type": "string",
            "enum": [
              "ERROR",
              "WARN",
              "INFO"
            ]
          },
          "attribute": {
            "type": "string",
            "description": "json path of request attribute that caused the error (if applicable)"
          },
          "ticketId": {
            "type": "string",
            "description": "internal ticket ID, used for error backtracking"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ]
      }
    }
  },
  "required": [
    "errors"
  ]
}

Delete a specific domestic payment order
DELETE/openapi/bankingExtension/v0/payments/domestic/{id}

Delete a specific domestic payment order.

This resource MAY require authorization, as indicated by status code 200 and authorization object in response.

URI Parameters
HideShow
id
number (required) Example: 123

Specific domestic payment order identifier.

Generated by aglio on 21 Mar 2024