Air Bank OpenAPI - GL CLient Identity

API Endpoint

This is documentation of the GL CLient Identity services of Air Bank OpenAPI.

Versions

Version num. Link Valid from Valid to
1 documentation 13.1.2018
added new attribute physicallyIdentified to User object 1.1.2021

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

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/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

To use GL Client Identity Services, you need a valid OAuth2 access token. Chapter Authentication describes how to get and use it.

Authentication

To access user sensitive data through API (use /openapi/banking 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 and client secret (note: those are different than apikey, used to access any resource from Open API).

  2. When you wish to access protected resource (pretty much anything under /openapi/banking 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 successful 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&redirect_uri=https%3A%2F%2Fyour.redirect.uri.cz%2F

    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 successful 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 retrieved 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 environment address
login page production https://ib.airbank.cz
token resource production https://api.airbank.cz/openapi/glClientIdentity/abauth/token

PersonalData

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

User information

GET /openapi/glClientIdentity/v1/personalData
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "gender": "M",
  "names": "John",
  "surname": "Doe",
  "birthNumber": "9103260936",
  "birthDate": "1991",
  "birthPlace": "Pelhřimov",
  "permanentAddress": {
    "country": "CZ",
    "municipality": "Kralupy nad Vltavou",
    "street": "Jana Palacha",
    "locality": "Devjvice",
    "buildingNumber": "897/13",
    "postalCode": "27801"
  },
  "citizenship": "CZ",
  "primaryPersonalDocument": {
    "type": "ID_CARD",
    "number": "4564654",
    "validTo": 1519686000000,
    "country": "CZ"
  },
  "politicallyExposedPerson": true,
  "physicallyIdentified": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "gender": {
      "type": "string"
    },
    "names": {
      "type": "string",
      "description": "user (given) names"
    },
    "surname": {
      "type": "string",
      "description": "user family name"
    },
    "birthNumber": {
      "type": "string",
      "description": "user birth number"
    },
    "birthDate": {
      "type": "string",
      "description": "03-26 (string, required) - user birth date"
    },
    "birthPlace": {
      "type": "string",
      "description": "user birth place"
    },
    "permanentAddress": {
      "type": "object",
      "properties": {
        "country": {
          "type": "string"
        },
        "municipality": {
          "type": "string"
        },
        "street": {
          "type": "string",
          "description": "one of street or locality is required"
        },
        "locality": {
          "type": "string",
          "description": "one of street or locality is required. present when there are no streets names."
        },
        "buildingNumber": {
          "type": "string",
          "description": "building number"
        },
        "postalCode": {
          "type": "string",
          "description": "zip code"
        }
      },
      "required": [
        "country",
        "municipality",
        "buildingNumber"
      ],
      "description": "permanent address"
    },
    "citizenship": {
      "type": "string",
      "description": "citizenship"
    },
    "primaryPersonalDocument": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "personal document type. Possible values: ID_CARD, FOREIGN_ID_CARD, DRIVE, GUN, PASSPORT, STAY_PERMIT, BIRTH, ID_CARD_SUBSTITUTED."
        },
        "number": {
          "type": "string",
          "description": "document number"
        },
        "validTo": {
          "type": "number",
          "description": "document date of expiration. UnixTime+TimeZone 3 digit."
        },
        "country": {
          "type": "string",
          "description": "country of the document issuer"
        }
      },
      "required": [
        "type",
        "number",
        "validTo"
      ],
      "description": "user primary personal document"
    },
    "politicallyExposedPerson": {
      "type": "boolean",
      "description": "if true person is politically exposed person"
    },
    "physicallyIdentified": {
      "type": "boolean",
      "description": "if true person was physically identified (in branch or by messenger), this attribute is since 1.1.2021"
    }
  },
  "required": [
    "gender",
    "names",
    "surname",
    "birthPlace",
    "permanentAddress",
    "primaryPersonalDocument",
    "politicallyExposedPerson",
    "physicallyIdentified"
  ]
}

Get user information
GET/openapi/glClientIdentity/v1/personalData

Get information about logged-in user.


Accounts

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

Account information

GET /openapi/glClientIdentity/v1/accounts
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "data": [
    {
      "accountNumber": {
        "prefix": "000000",
        "accountNumber": "1235335010",
        "bankCode": "3030",
        "iban": "CZ123456789",
        "bic": "AIRACZPP"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "accountNumber": {
            "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."
              },
              "iban": {
                "type": "string",
                "description": "account number in IBAN format"
              },
              "bic": {
                "type": "string",
                "description": "BIC for account"
              }
            },
            "required": [
              "accountNumber",
              "bankCode",
              "iban",
              "bic"
            ],
            "description": "AccountNumber object"
          }
        },
        "required": [
          "accountNumber"
        ]
      }
    }
  },
  "required": [
    "data"
  ]
}

Get list of accounts
GET/openapi/glClientIdentity/v1/accounts

Get a list of active and blocked accounts for logged-in user. Only show accounts that are owned by user.

Provided account types:

  • current accounts

  • savings accounts


Cards

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

Card information

GET /openapi/glClientIdentity/v1/cards
Responses200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "data": [
    {
      "cardNumber": "516822******1234"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "cardNumber": {
            "type": "string",
            "description": "masked card number"
          }
        },
        "required": [
          "cardNumber"
        ]
      }
    }
  },
  "required": [
    "data"
  ]
}

Get list of payment cards
GET/openapi/glClientIdentity/v1/cards

Get a list of payment cards for logged-in user. Only show cards belonging to accounts that are owned by user. Only active cards are retrieved.


Generated by aglio on 21 Mar 2024