Air Bank OpenAPI - AISP v3

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:

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:

• I. Certification Authority

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 ¶

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.

AISP ¶

AISP provides 3 services: Resources for obtaining account overview. You need valid OAuth2 access token to access this resources.

• Accounts Overview

• Account Balances

• Account Transactions