Air Bank OpenAPI - PISP v1

API Endpoint

This is documentation of the PISP services of Air Bank OpenAPI.

Access to this API can be granted only to entities holding a PSD2 license issued by the Czech National Bank or other relevant regulatory body.

Versions

Version num. Link Valid from Valid to
0 documentation 13.1.2018 1.6.2019
1 documentation 25.8.2018 31.8.2020
2 skipped
3 documentation 24.4.2020

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 size - number of items on the page
    • query parameter page - page number (starts from 0) parameter
  • on response:

    • pageNumber - current page
    • pageCount - total pages
    • pageSize - items per page
    • nextPage - next page number
    • totalCount - total number of items

Example request:

curl -X GET https://api.airbank.cz/openapi/accountInfo/v3/my/accounts?size=3&page=0}

Example response with pagingInfo:

{   "pageNumber": 0,
    "pageCount": 2,
    "pageSize": 3,
    "nextPage": 1,
    "totalCount": 5,
    "accounts": [
        {
            "id": "D2C8C1DCC51A3738538A40A4863CA288E0225E52",
            "identification":{
                "iban": "CZ0708000000001019382023",
            }

}

Sorting

  • some resources (stated in documentation) suppors result sorting. You can specify sorting attributes using sort request parameter.

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

Ordering

  • some resources (stated in documentation) suppors result ordering. You can specify ordering attributes using order request parameter.

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

Filtering

Some resources (stated in documentation) supports results filtering. Such resources have list of filters specified possible values. You can specify filtering by passing filter attribute.

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

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/accountInfo/v3/my/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 successful 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

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": [
  {
    "error": "PARAMETER_INVALID",
    "message": "Failed to parse date ["date']: Invalid number: date"
        }
    ],
}

Error object attributes

attribute name description
code http status
error error code
message human readable error description (non-localized)

Most important error codes

http status code error code description
401 UNAUTHORISED invalid access token
401 UNAUTHORISED invalid certificate
404 ID_NOT_FOUND account with id number not found
404 PAGE_NOT_FOUND page not found
400 PARAMETER_INVALID invalid parameter
400 DT01 invalid date
400 SORT_ERROR invalid sorting atribute
400 GENERAL_ERROR Unspecified (usually unexpected) error

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
  • numbers number format is defined by JSON standard, e.g. decimals are separated by .

  • strings (in requests)

    • text can’t contain separate “/” (slash) at the beginning or end, or two successive slashes
    • allowed characters: a-z A-Z 0-9 / - ? : ( ) . , ’ + _ Space

Sandbox

Sandbox

You can test your API integration with the Sandbox environment.

Endpoints

You can reach our sandbox environment at the following endpoint:

https://api.airbank.cz/sandbox

AISP - https://api.airbank.cz/sandbox/accountInfo/v3/my/accounts
PISP - https://api.airbank.cz/sandbox/paymentInit/v3/my/payments
CISP - use balanceCheck from PISP (same contract)

Authentication for Sandbox

For sandbox environment, you can use following secrets:

clientId clientSecret
sandbox_client_id sandbox_client_secret

To retrieve OAuth2 grant code for the sandbox environment, redirect user to login page:

http://developers.airbank.cz/sandbox/login?state=YOUR_STATE_CODE&redirectUri=https://www.airbank.cz

You can use any login. You will be redirected to the given redirectUri with the parameter code you can use in the OAuth2 flow at the following endpoint:

https://api.airbank.cz/sandbox/oauth2/token

Then you can access all the sandbox APIs normally with the returned access_token.

Data

  • There are sample data returned for getAccounts call

  • Transactions are returned only for the account with ID 10000411

  • Payments can be made from the account CZ5430300000001000053019

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

    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 NOTE: You must keep your client secret safe. It serves as your application password.

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 enviroment 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. Use API resources to initiate and grab the authorization result.

Authorization object

Parameters of authorization are returned as a result of sensitive active operation by creating payment order /openapi/paymentInit/v1/my/payments. Authorization object has following structure:

{
  "transactionIdentification": "100010771",
  "serviceLevel": {
    "code": "DOMESTIC"
  },
  "signInfo": {
    "state": "IN_PROGRESS",
    "signId": "rTkaVG0toaZAWXnPHI.DRo_iF1Q6ZucC.GcSWXGTWfyMVObHfgFkKy_BsLu7cYiGpFtZcdYhwVr7NUcu4p2MVg4a09xsdkmexe1tujY5xLM9.BMHV67kPU2DIH5p9cVL",
    "signInfo": "ACTC"
  }
}

Authorization resource

Resource for GET Authorization URL /openapi/paymentInit/v1/my/payments/{paymentId}/sign/{signId}. Parameter hrefURL is returned in response object.

  • paymentId: Payment order identifier - parameter transactionIdentification from authorization object.

  • signId: Internal authorization request identifier, expect arbitrary long string.

{
  "scenarios": [
    {
      "type": "SMS",
      "hrefUrl": "https://www.airbank.cz/authorization?authId=awH5ngEBtL8ONThT73xvhDvbdDawDMEUFG7obwNQP392GAyb8xGe0UURB18REwsrESS6RcKoZfyfXQwBUP3SlFS.1pqOjMkVm4SR56jBqcY.40oBWCRrswT1GQFn0aGB",
      "method": "GET"
    }
  ],
  "signInfo": {
    "state": "IN_PROGRESS",
    "signId": "awH5ngEBtL8ONThT73xvhDvbdDawDMEUFG7obwNQP392GAyb8xGe0UURB18REwsrESS6RcKoZfyfXQwBUP3SlFS.1pqOjMkVm4SR56jBqcY.40oBWCRrswT1GQFn0aGB"
  }
}

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.


Payments

Payment order resources. You need valid OAuth2 access token to access these resources.

Payment Initiation Service Providers (PISP)

This API specification is based on PSD2 (revised Payment Services Directive) and depends on COBS standards. It provides implementation COBS features with some differences described below.

Allowed HTTPs Requests

  • [POST] Send payment order

  • [POST] Check for sufficient funds

  • [GET] Request for payment order detail

  • [DELETE] Delete unauthorized payment order

  • [GET] Request for payment order status

  • [GET] Request for payment authorization

List of possible error codes in response

HTTP Status code API Error code Description
400 FIELD_MISSING Missing mandatory field in request
400 FIELD_INVALID The field value is not valid
400 PARAMETER_INVALID The value of the parameter is not valid
400 AC02 InvalidDebtorAccountNumber - An invalid account identifier in the content of the request
400 AC09 InvalidAccountCurrency - Invalid currency of required account
400 AM11 InvalidTransactionCurrency - The request contains a non-traded / unsupported currency
400 AM12 InvalidAmount - Misplaced amount. E.g. too low or a high amount or a bad number format including the number of decimal places according to ISO 4217
400 FF01 InvalidFileFormat - Invalid JSON format or other technical issue with request processing
400 NARR Narrative - General reason for declining payment, with information about the error
400 RF01 NotUniqueTransactionReference - Non-unique request identifier
400 RR10 InvalidCharacterSet - Invalid character set in request
401 UNAUTHORIZED Invalid or missing access token, user is not authenticated
401 UNAUTHORIZED Invalid or missing certificate, provider is not authenticated
403 FORBIDDEN Access to the requested resource is not granted or is not possible for that user
404 PAGE_NOT_FOUND Request for non-existent page

New payment

POST /openapi/paymentInit/v1/my/payments
RequestsDOMESTICSEPAEHPNONEHP
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer AbCdEf123456
Body
{
  "paymentIdentification": {
    "instructionIdentification": "NejakeID41785962314574"
  },
  "paymentTypeInformation": {
    "instructionPriority": "NORM"
  },
  "amount": {
    "instructedAmount": {
      "value": 1048.64,
      "currency": "CZK"
    }
  },
  "requestedExecutionDate": "2018-06-01",
  "debtorAccount": {
    "identification": {
      "iban": "CZ7508000000002108589434"
    }
  },
  "creditorAccount": {
    "identification": {
      "iban": "CZ6330300000000000000123"
    },
    "currency": "CZK"
  },
  "remittanceInformation": {
    "unstructured": "VS/7418529630/SS/1234567890",
    "structured": {
      "creditorReferenceInformation": {
        "reference": [
          "VS:5010000000",
          "KS:9",
          "SS:1005"
        ]
      }
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "paymentIdentification": {
      "type": "object",
      "properties": {
        "instructionIdentification": {
          "type": "string"
        }
      }
    },
    "paymentTypeInformation": {
      "type": "object",
      "properties": {
        "instructionPriority": {
          "type": "string",
          "enum": [
            "NORM"
          ]
        }
      }
    },
    "amount": {
      "type": "object",
      "properties": {
        "instructedAmount": {
          "type": "object",
          "properties": {
            "value": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            }
          },
          "required": [
            "value",
            "currency"
          ]
        }
      },
      "required": [
        "instructedAmount"
      ]
    },
    "requestedExecutionDate": {
      "type": "string"
    },
    "debtorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            }
          },
          "required": [
            "iban"
          ]
        }
      },
      "required": [
        "identification"
      ]
    },
    "creditorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            }
          },
          "required": [
            "iban"
          ]
        },
        "currency": {
          "type": "string"
        }
      },
      "required": [
        "identification"
      ]
    },
    "remittanceInformation": {
      "type": "object",
      "properties": {
        "unstructured": {
          "type": "string"
        },
        "structured": {
          "type": "object",
          "properties": {
            "creditorReferenceInformation": {
              "type": "object",
              "properties": {
                "reference": {
                  "type": "array"
                }
              }
            }
          }
        }
      }
    }
  },
  "required": [
    "paymentIdentification",
    "amount",
    "debtorAccount",
    "creditorAccount"
  ]
}
Responses200400401403
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "transactionIdentification": "100010771",
  "serviceLevel": {
    "code": "DOMESTIC"
  },
  "signInfo": {
    "state": "IN_PROGRESS",
    "signId": "rTkaVG0toaZAWXnPHI.DRo_iF1Q6ZucC.GcSWXGTWfyMVObHfgFkKy_BsLu7cYiGpFtZcdYhwVr7NUcu4p2MVg4a09xsdkmexe1tujY5xLM9.BMHV67kPU2DIH5p9cVL",
    "signInfo": "ACTC"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transactionIdentification": {
      "type": "string"
    },
    "serviceLevel": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "DOMESTIC",
            "SEPA",
            "EHP",
            "NONEHP"
          ]
        }
      },
      "required": [
        "code"
      ]
    },
    "signInfo": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "IN_PROGRESS",
            "AUTHORIZED",
            "REJECTED",
            "TIMEOUTED",
            "NO_AUTHORIZATION_METHOD"
          ]
        },
        "signId": {
          "type": "string"
        },
        "signInfo": {
          "type": "string",
          "enum": [
            "ACTC",
            "RJCT",
            "ACSP",
            "ACSC",
            "ACWC"
          ]
        }
      },
      "required": [
        "state",
        "signInfo"
      ]
    }
  },
  "required": [
    "transactionIdentification",
    "serviceLevel",
    "signInfo"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "AC02",
      "message": "invalid IBAN value",
      "scope": "debtorAccount.identification.iban"
    },
    {
      "error": "FIELD_MISSING",
      "message": "may not be null",
      "scope": "transactionDetail.totalAmount"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "UNAUTHORIZED"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "FORBIDDEN"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer AbCdEf123456
Body
{
  "paymentIdentification": {
    "instructionIdentification": "SEPAFUL123",
    "endToEndIdentification": "123"
  },
  "paymentTypeInformation": {
    "instructionPriority": "NORM"
  },
  "amount": {
    "instructedAmount": {
      "value": 1048.64,
      "currency": "EUR"
    }
  },
  "requestedExecutionDate": "2018-06-01",
  "debtorAccount": {
    "identification": {
      "iban": "CZ7830300000001000000013"
    }
  },
  "creditorAgent": {
    "financialInstitutionIdentification": {
      "bic": "RZBAATWWXXX"
    }
  },
  "creditor": {
    "name": "1. wiena investment",
    "postalAddress": {
      "streetName": "Reisnerstraße",
      "buildingNumber": "20",
      "postCode": "1030",
      "townName": "Wiena",
      "country": "AT",
      "addressLine": [
        "address line 1",
        "address line 2"
      ]
    }
  },
  "creditorAccount": {
    "identification": {
      "iban": "AT033363343184694213"
    }
  },
  "purpose": {
    "code": "1e2",
    "proprietary": "sale of shares"
  },
  "remittanceInformation": {
    "unstructured": "VS/7418529630/SS/1234567890"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "paymentIdentification": {
      "type": "object",
      "properties": {
        "instructionIdentification": {
          "type": "string"
        },
        "endToEndIdentification": {
          "type": "string"
        }
      }
    },
    "paymentTypeInformation": {
      "type": "object",
      "properties": {
        "instructionPriority": {
          "type": "string",
          "enum": [
            "NORM"
          ]
        }
      }
    },
    "amount": {
      "type": "object",
      "properties": {
        "instructedAmount": {
          "type": "object",
          "properties": {
            "value": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            }
          },
          "required": [
            "value",
            "currency"
          ]
        }
      },
      "required": [
        "instructedAmount"
      ]
    },
    "requestedExecutionDate": {
      "type": "string"
    },
    "debtorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            }
          },
          "required": [
            "iban"
          ]
        }
      },
      "required": [
        "identification"
      ]
    },
    "creditorAgent": {
      "type": "object",
      "properties": {
        "financialInstitutionIdentification": {
          "type": "object",
          "properties": {
            "bic": {
              "type": "string"
            }
          },
          "required": [
            "bic"
          ]
        }
      }
    },
    "creditor": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "postalAddress": {
          "type": "object",
          "properties": {
            "streetName": {
              "type": "string"
            },
            "buildingNumber": {
              "type": "string"
            },
            "postCode": {
              "type": "string"
            },
            "townName": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "addressLine": {
              "type": "array"
            }
          }
        }
      },
      "required": [
        "name"
      ]
    },
    "creditorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            }
          },
          "required": [
            "iban"
          ]
        }
      },
      "required": [
        "identification"
      ]
    },
    "purpose": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "proprietary": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "proprietary"
      ]
    },
    "remittanceInformation": {
      "type": "object",
      "properties": {
        "unstructured": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "paymentIdentification",
    "amount",
    "debtorAccount",
    "creditor",
    "creditorAccount"
  ]
}
Responses200400401403
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "transactionIdentification": "100010771",
  "serviceLevel": {
    "code": "SEPA"
  },
  "signInfo": {
    "state": "IN_PROGRESS",
    "signId": "rTkaVG0toaZAWXnPHI.DRo_iF1Q6ZucC.GcSWXGTWfyMVObHfgFkKy_BsLu7cYiGpFtZcdYhwVr7NUcu4p2MVg4a09xsdkmexe1tujY5xLM9.BMHV67kPU2DIH5p9cVL",
    "signInfo": "ACTC"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transactionIdentification": {
      "type": "string"
    },
    "serviceLevel": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "SEPA",
            "DOMESTIC",
            "EHP",
            "NONEHP"
          ]
        }
      },
      "required": [
        "code"
      ]
    },
    "signInfo": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "IN_PROGRESS",
            "AUTHORIZED",
            "REJECTED",
            "TIMEOUTED",
            "NO_AUTHORIZATION_METHOD"
          ]
        },
        "signId": {
          "type": "string"
        },
        "signInfo": {
          "type": "string",
          "enum": [
            "ACTC",
            "RJCT",
            "ACSP",
            "ACSC",
            "ACWC"
          ]
        }
      },
      "required": [
        "state",
        "signInfo"
      ]
    }
  },
  "required": [
    "transactionIdentification",
    "serviceLevel",
    "signInfo"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "AC02",
      "message": "invalid IBAN value",
      "scope": "debtorAccount.identification.iban"
    },
    {
      "error": "FIELD_MISSING",
      "message": "may not be null",
      "scope": "transactionDetail.totalAmount"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "UNAUTHORIZED"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "FORBIDDEN"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer AbCdEf123456
Body
{
  "paymentIdentification": {
    "instructionIdentification": "MOJeID1234"
  },
  "paymentTypeInformation": {
    "instructionPriority": "NORM"
  },
  "amount": {
    "instructedAmount": {
      "value": 1048.64,
      "currency": "USD"
    }
  },
  "requestedExecutionDate": "2018-06-01",
  "chargeBearer": "DEBT",
  "debtorAccount": {
    "identification": {
      "iban": "CZ8601000000000161486937"
    }
  },
  "creditorAgent": {
    "financialInstitutionIdentification": {
      "bic": "GIBACZPX"
    }
  },
  "creditor": {
    "name": "Bohumil Hrabal",
    "postalAddress": {
      "streetName": "Na Hrázi",
      "buildingNumber": "326/24",
      "postCode": "18000",
      "townName": "Praha 8",
      "country": "CZ",
      "addressLine": [
        "address line 1",
        "address line 2"
      ]
    }
  },
  "creditorAccount": {
    "identification": {
      "iban": "CZ3908000000000204533335"
    }
  },
  "remittanceInformation": {
    "unstructured": "fa 123546897"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "paymentIdentification": {
      "type": "object",
      "properties": {
        "instructionIdentification": {
          "type": "string"
        }
      }
    },
    "paymentTypeInformation": {
      "type": "object",
      "properties": {
        "instructionPriority": {
          "type": "string",
          "enum": [
            "NORM"
          ]
        }
      }
    },
    "amount": {
      "type": "object",
      "properties": {
        "instructedAmount": {
          "type": "object",
          "properties": {
            "value": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            }
          },
          "required": [
            "value",
            "currency"
          ]
        }
      },
      "required": [
        "instructedAmount"
      ]
    },
    "requestedExecutionDate": {
      "type": "string"
    },
    "chargeBearer": {
      "type": "string",
      "enum": [
        "DEBT",
        "CRED",
        "SHAR",
        "SLEV"
      ]
    },
    "debtorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            }
          },
          "required": [
            "iban"
          ]
        }
      },
      "required": [
        "identification"
      ]
    },
    "creditorAgent": {
      "type": "object",
      "properties": {
        "financialInstitutionIdentification": {
          "type": "object",
          "properties": {
            "bic": {
              "type": "string"
            }
          },
          "required": [
            "bic"
          ]
        }
      },
      "required": [
        "financialInstitutionIdentification"
      ]
    },
    "creditor": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "postalAddress": {
          "type": "object",
          "properties": {
            "streetName": {
              "type": "string"
            },
            "buildingNumber": {
              "type": "string"
            },
            "postCode": {
              "type": "string"
            },
            "townName": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "addressLine": {
              "type": "array"
            }
          }
        }
      },
      "required": [
        "name"
      ]
    },
    "creditorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            }
          },
          "required": [
            "iban"
          ]
        }
      },
      "required": [
        "identification"
      ]
    },
    "remittanceInformation": {
      "type": "object",
      "properties": {
        "unstructured": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "paymentIdentification",
    "amount",
    "debtorAccount",
    "creditorAgent",
    "creditor",
    "creditorAccount"
  ]
}
Responses200400401403
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "transactionIdentification": "100010771",
  "serviceLevel": {
    "code": "EHP"
  },
  "signInfo": {
    "state": "IN_PROGRESS",
    "signId": "rTkaVG0toaZAWXnPHI.DRo_iF1Q6ZucC.GcSWXGTWfyMVObHfgFkKy_BsLu7cYiGpFtZcdYhwVr7NUcu4p2MVg4a09xsdkmexe1tujY5xLM9.BMHV67kPU2DIH5p9cVL",
    "signInfo": "ACTC"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transactionIdentification": {
      "type": "string"
    },
    "serviceLevel": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "EHP",
            "SEPA",
            "DOMESTIC",
            "NONEHP"
          ]
        }
      },
      "required": [
        "code"
      ]
    },
    "signInfo": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "IN_PROGRESS",
            "AUTHORIZED",
            "REJECTED",
            "TIMEOUTED",
            "NO_AUTHORIZATION_METHOD"
          ]
        },
        "signId": {
          "type": "string"
        },
        "signInfo": {
          "type": "string",
          "enum": [
            "ACTC",
            "RJCT",
            "ACSP",
            "ACSC",
            "ACWC"
          ]
        }
      },
      "required": [
        "state",
        "signInfo"
      ]
    }
  },
  "required": [
    "transactionIdentification",
    "serviceLevel",
    "signInfo"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "AC02",
      "message": "invalid IBAN value",
      "scope": "debtorAccount.identification.iban"
    },
    {
      "error": "FIELD_MISSING",
      "message": "may not be null",
      "scope": "transactionDetail.totalAmount"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "UNAUTHORIZED"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "FORBIDDEN"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer AbCdEf123456
Body
{
  "paymentIdentification": {
    "instructionIdentification": "IDTPP45678911"
  },
  "paymentTypeInformation": {
    "instructionPriority": "NORM"
  },
  "amount": {
    "instructedAmount": {
      "value": 1048.64,
      "currency": "GBP"
    }
  },
  "requestedExecutionDate": "2018-06-01",
  "chargeBearer": "DEBT",
  "debtorAccount": {
    "identification": {
      "iban": "CZ6330300000000000000123"
    },
    "currency": "CZK"
  },
  "creditorAgent": {
    "financialInstitutionIdentification": {
      "bic": "ABNYUS33",
      "name": "New York Commercial Bank",
      "postalAddress": {
        "streetName": "Merrick Avenue615",
        "buildingNumber": "61511590",
        "postCode": "11590",
        "townName": "WESTBURY, NY",
        "country": "USA",
        "addressLine": [
          "address line 1",
          "address line 2"
        ]
      }
    }
  },
  "creditor": {
    "name": "First Hudson boat Inc.",
    "postalAddress": {
      "streetName": "Grand St",
      "buildingNumber": "1256",
      "postCode": "NY 11211",
      "townName": "Brooklyn, NY",
      "country": "USA",
      "addressLine": [
        "address line 1",
        "address line 2"
      ]
    }
  },
  "creditorAccount": {
    "identification": {
      "other": {
        "identification": "123456789"
      }
    }
  },
  "remittanceInformation": {
    "unstructured": "fa 123546897"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "paymentIdentification": {
      "type": "object",
      "properties": {
        "instructionIdentification": {
          "type": "string"
        }
      }
    },
    "paymentTypeInformation": {
      "type": "object",
      "properties": {
        "instructionPriority": {
          "type": "string",
          "enum": [
            "NORM"
          ]
        }
      }
    },
    "amount": {
      "type": "object",
      "properties": {
        "instructedAmount": {
          "type": "object",
          "properties": {
            "value": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            }
          },
          "required": [
            "value",
            "currency"
          ]
        }
      },
      "required": [
        "instructedAmount"
      ]
    },
    "requestedExecutionDate": {
      "type": "string"
    },
    "chargeBearer": {
      "type": "string",
      "enum": [
        "DEBT",
        "SHAR"
      ]
    },
    "debtorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string"
            }
          },
          "required": [
            "iban"
          ]
        },
        "currency": {
          "type": "string"
        }
      },
      "required": [
        "identification"
      ]
    },
    "creditorAgent": {
      "type": "object",
      "properties": {
        "financialInstitutionIdentification": {
          "type": "object",
          "properties": {
            "bic": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "postalAddress": {
              "type": "object",
              "properties": {
                "streetName": {
                  "type": "string"
                },
                "buildingNumber": {
                  "type": "string",
                  "description": "6644"
                },
                "postCode": {
                  "type": "string",
                  "description": "6644"
                },
                "townName": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "addressLine": {
                  "type": "array"
                }
              }
            }
          },
          "required": [
            "bic"
          ]
        }
      },
      "required": [
        "financialInstitutionIdentification"
      ]
    },
    "creditor": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "postalAddress": {
          "type": "object",
          "properties": {
            "streetName": {
              "type": "string"
            },
            "buildingNumber": {
              "type": "string"
            },
            "postCode": {
              "type": "string"
            },
            "townName": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "addressLine": {
              "type": "array"
            }
          }
        }
      },
      "required": [
        "name"
      ]
    },
    "creditorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "other": {
              "type": "object",
              "properties": {
                "identification": {
                  "type": "string"
                }
              },
              "required": [
                "identification"
              ]
            }
          },
          "required": [
            "other"
          ]
        }
      },
      "required": [
        "identification"
      ]
    },
    "remittanceInformation": {
      "type": "object",
      "properties": {
        "unstructured": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "paymentIdentification",
    "amount",
    "chargeBearer",
    "debtorAccount",
    "creditorAgent",
    "creditor",
    "creditorAccount"
  ]
}
Responses200400401403
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "transactionIdentification": "100010771",
  "serviceLevel": {
    "code": "NONEHP"
  },
  "signInfo": {
    "state": "IN_PROGRESS",
    "signId": "rTkaVG0toaZAWXnPHI.DRo_iF1Q6ZucC.GcSWXGTWfyMVObHfgFkKy_BsLu7cYiGpFtZcdYhwVr7NUcu4p2MVg4a09xsdkmexe1tujY5xLM9.BMHV67kPU2DIH5p9cVL",
    "signInfo": "ACTC"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transactionIdentification": {
      "type": "string"
    },
    "serviceLevel": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "NONEHP",
            "EHP",
            "SEPA",
            "DOMESTIC"
          ]
        }
      },
      "required": [
        "code"
      ]
    },
    "signInfo": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "IN_PROGRESS",
            "AUTHORIZED",
            "REJECTED",
            "TIMEOUTED",
            "NO_AUTHORIZATION_METHOD"
          ]
        },
        "signId": {
          "type": "string"
        },
        "signInfo": {
          "type": "string",
          "enum": [
            "ACTC",
            "RJCT",
            "ACSP",
            "ACSC",
            "ACWC"
          ]
        }
      },
      "required": [
        "state",
        "signInfo"
      ]
    }
  },
  "required": [
    "transactionIdentification",
    "serviceLevel",
    "signInfo"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "AC02",
      "message": "invalid IBAN value",
      "scope": "debtorAccount.identification.iban"
    },
    {
      "error": "FIELD_MISSING",
      "message": "may not be null",
      "scope": "transactionDetail.totalAmount"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "UNAUTHORIZED"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "FORBIDDEN"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

Send new payment order
POST/openapi/paymentInit/v1/my/payments

Create a new payment order.


Request Structure

  • [M] - Mandatory field (if superior field exist)

  • [Mc] - Conditional mandatory field

  • [Opt] - Optional field

  • [×] - Field is forbidden

  • + (superior field)  «  ++ (inner field)

Structure Field DOMESTIC SEPA EHP NONEHP Note
+ paymentIdentification M M M M
++ instructionIdentification M M M M Max35Text
++ endToEndIdentification × M × × Max35Text
+ paymentTypeInformation Opt Opt Opt Opt
++ instructionPriority Opt Opt Opt Opt NORM
+ amount M M M M
++ instructedAmount M M M M
+++ value M M M M Number
+++ currency M M M M ISO 4217
+ requestedExecutionDate Opt Opt Opt Opt
+ chargeBearer × × Opt Opt
+ debtorAccount M M M M
++ identification M M M M
+++ iban M M M M ISO 13616
+ creditorAgent × Opt M M
++ financialInstitutionIdentification × Opt M M
+++ bic × M M M
+++ name × × × M
+++ postalAddress × × × M
++++ streetName × × × Mc Max70Text, Mandatory or addressLine
++++ buildingNumber × × × Mc Max16Text, Mandatory or addressLine
++++ postCode × × × Mc Max16Text, Mandatory or addressLine
++++ townName × × × Mc Max35Text, Mandatory or addressLine
++++ country × × × M ISO 3166
++++ addressLine × × × Mc Max70Text, Mandatory or structured address
+++ other × × × Opt
+ creditor × M M M
++ name × M M M
++ postalAddress × Opt Opt M
+++ streetName × Opt Opt Opt Max70Text
+++ buildingNumber × Opt Opt Opt Max16Text
+++ postCode × Opt Opt Opt Max16Text
+++ townName × Opt Opt Opt Max35Text
+++ country × Opt Opt Opt ISO 3166
+++ addressLine × Opt Opt Opt Max70Text
+ creditorAccount M M M M
++ identification M M M M
+++ iban M M Mc Mc iban or other must exist, ISO 13616
+++ other × × Mc Mc iban or other must exist
++++ identification × × M M
++ currency Opt × × × ISO 4217
+ purpose × Opt × ×
++ code × M × ×
++ proprietary × M × × Max35Text
+ remittanceInformation Opt Opt Opt Opt
++ unstructured Opt Opt Opt Opt Max140Text
++ structured Opt × × ×
+++ creditorReferenceInformation Opt × × ×
++++ reference Opt × × × Array of string values VS, KS, SS

Response Structure

Structure Field DOMESTIC SEPA EHP NONEHP Note
+ transactionIdentification M M M M Max35Text
+ serviceLevel M M M M
++ code M M M M DOMESTIC, SEPA, EHP, NONEHP
+ signInfo M M M M
++ state M M M M *
++ signId Opt Opt Opt Opt The signId is filled in if a payment order has been received and an authorization has been started (the client has set the correct element)
++ signInfo M M M M ACTC, RJCT, ACSP, ACSC, ACWC
* signInfo.state enumeration
  • IN_PROGRESS - Authorization has been initiated and is still in progress.

  • AUTHORIZED - Authorization has been authorized - confirmed by one of the allowed methods.

  • REJECTED - Authorization has been rejected by user, invalid attempts or authorization alive countdown time limit passed.

  • TIMEOUTED - Authorization has timeouted, time given to process authorization has passed (transaction cannot be authorized anymore, should be treated as rejected).

  • NO_AUTHORIZATION_METHOD - No authorization method available for specified parameters


Balance check

POST /openapi/paymentInit/v1/my/payments/balanceCheck
RequestsBalance Check
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer AbCdEf123456
Body
{
  "exchangeIdentification": "123456",
  "debtorAccount": {
    "identification": {
      "iban": "CZ0708000000001019382023"
    },
    "currency": "CZK"
  },
  "merchant": {
    "identification": "471 16 129",
    "type": "code",
    "shortName": "NEOLUXOR",
    "commonName": "Neoluxor s.r.o.",
    "address": "Hlavní 5, Praha 1",
    "countryCode": "CZ",
    "merchantCategoryCode": "5192"
  },
  "transactionDetails": {
    "currency": "CZK",
    "totalAmount": 10050.15
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "exchangeIdentification": {
      "type": "string",
      "description": "Unique request identification"
    },
    "debtorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "iban": {
              "type": "string",
              "description": "Account identification in IBAN format"
            }
          },
          "required": [
            "iban"
          ],
          "description": "Debtor account identification"
        },
        "currency": {
          "type": "string",
          "description": "Debtor account currency"
        }
      },
      "required": [
        "identification"
      ]
    },
    "merchant": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "shortName": {
          "type": "string"
        },
        "commonName": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "countryCode": {
          "type": "string"
        },
        "merchantCategoryCode": {
          "type": "string"
        }
      },
      "required": [
        "identification",
        "shortName",
        "commonName",
        "merchantCategoryCode"
      ]
    },
    "transactionDetails": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "description": "Transaction currency"
        },
        "totalAmount": {
          "type": "number",
          "description": "Transaction total amount"
        }
      },
      "required": [
        "currency",
        "totalAmount"
      ]
    }
  },
  "required": [
    "exchangeIdentification",
    "debtorAccount"
  ]
}
Responses200400401403
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "responseIdentification": 98765,
  "exchangeIdentification": 123456,
  "response": "APPR"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "responseIdentification": {
      "type": "number"
    },
    "exchangeIdentification": {
      "type": "number"
    },
    "response": {
      "type": "string",
      "enum": [
        "APPR",
        "DECL"
      ]
    }
  },
  "required": [
    "responseIdentification",
    "exchangeIdentification",
    "response"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "AC02",
      "message": "invalid IBAN value",
      "scope": "debtorAccount.identification.iban"
    },
    {
      "error": "FIELD_MISSING",
      "message": "may not be null",
      "scope": "transactionDetail.totalAmount"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "UNAUTHORIZED"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "FORBIDDEN"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

Check for sufficient funds
POST/openapi/paymentInit/v1/my/payments/balanceCheck

Resource for sending a query for sufficient funds to a specific account payer’s payment account. This resource is authorized. Access to information must be granted by the client outside the interaction of this API before the resource is used.


Request Structure

  • [M] - Mandatory field (if superior field exist)

  • + (superior field)  «  ++ (inner field)

Structure Field Mandatory Note
+ exchangeIdentification M
+ debtorAccount M
++ identification M
+++ iban M ISO 13616
++ currency M ISO 4217
+ merchant
++ identification M
++ type
++ shortName M
++ commonName M
++ address
++ countryCode ISO 3166
++ merchantCategoryCode M
+ transactionDetails
++ currency M ISO 4217
++ totalAmount M Number

Response Structure

Structure Field Mandatory Note
+ responseIdentification M
+ exchangeIdentification M
+ response M

Payment detail

GET /openapi/paymentInit/v1/my/payments/048885570000001020045
RequestsGet Payment Detail
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer AbCdEf123456
Responses200401403404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "paymentIdentification": {
    "instructionIdentification": "100010771",
    "endToEndIdentification": "123"
  },
  "paymentTypeInformation": {
    "instructionPriority": "NORM"
  },
  "amount": {
    "instructedAmount": {
      "value": "1048.64",
      "currency": "EUR"
    }
  },
  "requestedExecutionDate": "2123-08-01T22:00:00Z",
  "chargeBearer": "SHAR",
  "creditorAgent": {
    "financialInstitutionIdentification": {
      "bic": "RZBAATWWXXX",
      "name": "RAIFFEISEN BANK INTERNATIONAL AG",
      "postalAddress": {
        "country": "AT",
        "addressLine": [
          "AM STADTPARK 9 VIENNA 1030"
        ]
      }
    }
  },
  "creditor": {
    "name": "1. wiena investment",
    "postalAddress": {
      "country": "AT",
      "addressLine": [
        "address line 1",
        "address line 2"
      ]
    }
  },
  "remittanceInformation": {
    "unstructured": "VS/7418529630/SS/1234567890",
    "structured": {
      "creditorReferenceInformation": {
        "reference": [
          "VS/7418529630",
          "SS/1234567890"
        ]
      }
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "paymentIdentification": {
      "type": "object",
      "properties": {
        "instructionIdentification": {
          "type": "string"
        },
        "endToEndIdentification": {
          "type": "string"
        }
      }
    },
    "paymentTypeInformation": {
      "type": "object",
      "properties": {
        "instructionPriority": {
          "type": "string",
          "enum": [
            "NORM"
          ]
        }
      }
    },
    "amount": {
      "type": "object",
      "properties": {
        "instructedAmount": {
          "type": "object",
          "properties": {
            "value": {
              "type": "string"
            },
            "currency": {
              "type": "string"
            }
          }
        }
      }
    },
    "requestedExecutionDate": {
      "type": "string"
    },
    "chargeBearer": {
      "type": "string",
      "enum": [
        "SHAR",
        "DEBT",
        "CRED",
        "SLEV"
      ]
    },
    "creditorAgent": {
      "type": "object",
      "properties": {
        "financialInstitutionIdentification": {
          "type": "object",
          "properties": {
            "bic": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "postalAddress": {
              "type": "object",
              "properties": {
                "country": {
                  "type": "string"
                },
                "addressLine": {
                  "type": "array"
                }
              }
            }
          }
        }
      }
    },
    "creditor": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "postalAddress": {
          "type": "object",
          "properties": {
            "country": {
              "type": "string"
            },
            "addressLine": {
              "type": "array"
            }
          }
        }
      }
    },
    "remittanceInformation": {
      "type": "object",
      "properties": {
        "unstructured": {
          "type": "string"
        },
        "structured": {
          "type": "object",
          "properties": {
            "creditorReferenceInformation": {
              "type": "object",
              "properties": {
                "reference": {
                  "type": "array"
                }
              }
            }
          }
        }
      }
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "UNAUTHORIZED"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "FORBIDDEN"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "NOT_FOUND"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

Get payment detail
GET/openapi/paymentInit/v1/my/payments/{paymentId}

Request for payment detail

URI Parameters
HideShow
paymentId
string (required) Example: 048885570000001020045

Payment identification


DELETE /openapi/paymentInit/v1/my/payments/048885570000001020045
RequestsDelete Payment
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer AbCdEf123456
Responses204
This response has no content.

Delete payment
DELETE/openapi/paymentInit/v1/my/payments/{paymentId}

Delete set or unauthorized payment

URI Parameters
HideShow
paymentId
string (required) Example: 048885570000001020045

Payment identification


Payment status

GET /openapi/paymentInit/v1/my/payments/048885570000001020045/status
RequestsGet Payment Status
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer AbCdEf123456
Responses200401403404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "instructionStatus": "ACTC"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "instructionStatus": {
      "type": "string",
      "enum": [
        "ACTC",
        "RJCT",
        "ACSP",
        "ACSC",
        "ACWC"
      ]
    }
  },
  "required": [
    "instructionStatus"
  ]
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "UNAUTHORIZED"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "FORBIDDEN"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "NOT_FOUND"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

Get payment status
GET/openapi/paymentInit/v1/my/payments/{paymentId}/status

Request for payment status

URI Parameters
HideShow
paymentId
string (required) Example: 048885570000001020045

Payment identification


Payment authorization

GET /openapi/paymentInit/v1/my/payments/048885570000001020045/sign/164298331754922
RequestsGet Payment Authorization
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer AbCdEf123456
Responses200401403404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "scenarios": [
    {
      "type": "SMS",
      "hrefUrl": "https://www.airbank.cz/authorization?authId=awH5ngEBtL8ONThT73xvhDvbdDawDMEUFG7obwNQP392GAyb8xGe0UURB18REwsrESS6RcKoZfyfXQwBUP3SlFS.1pqOjMkVm4SR56jBqcY.40oBWCRrswT1GQFn0aGB",
      "method": "GET"
    }
  ],
  "signInfo": {
    "state": "IN_PROGRESS",
    "signId": "awH5ngEBtL8ONThT73xvhDvbdDawDMEUFG7obwNQP392GAyb8xGe0UURB18REwsrESS6RcKoZfyfXQwBUP3SlFS.1pqOjMkVm4SR56jBqcY.40oBWCRrswT1GQFn0aGB"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "scenarios": {
      "type": "array"
    },
    "signInfo": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string"
        },
        "signId": {
          "type": "string"
        }
      }
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "UNAUTHORIZED"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "FORBIDDEN"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "error": "NOT_FOUND"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

Get payment authorization
GET/openapi/paymentInit/v1/my/payments/{paymentId}/sign/{signId}

Request for payment authorization

Response scenario types

  • CONFIRMATION - Authorization method uses authorization element CONFIRMATION.

  • PWD - Authorization method uses authorization element PWD.

  • SMS - Authorization method uses authorization element SMS.

  • PWD_SMS - Authorization method uses sequence of two authorization elements PWD, SMS.

  • VERBAL_APPROVAL - Authorization method uses authorization element VERBAL_APPROVAL.

  • SWT_ONLINE - Authorization method uses authorization element SWT_ONLINE.

  • PWD_SWT_ONLINE - Authorization method uses sequence of two authorization elements PWD, SWT_ONLINE.

  • PWD_SWT_ONLINE_CONFIRMATION - Authorization method uses sequence of two authorization elements PWD, SWT_ONLINE_CONFIRMATION

  • SWT_OFFLINE - Authorization method uses authorization element SWT_OFFLINE.

  • PWD_SWT_OFFLINE - Authorization method uses sequence of two authorization elements PWD, SWT_OFFLINE.

  • SWT_ONLINE_CONFIRMATION - Authorization method uses authorization element SWT_ONLINE_CONFIRMATION.

  • HWT - Authorization method uses authorization element HWT.

  • PWD_HWT - Authorization method uses sequence of two authorization elements PWD, HWT.

URI Parameters
HideShow
paymentId
string (required) Example: 048885570000001020045

Payment identification

signId
string (required) Example: 164298331754922

Sign id


Generated by aglio on 09 Aug 2021