Access To Accounts

Overview

The Account Information Service (AIS) enables TPPs to access account information of a Payment Service User (PSU). To access the account information, TPP must first create a consent and have it approved by PSU. With the approved consent, TPP can retrieve PSU's account information: balances, transaction history, and other pertinent details.

Flow description

Below is the description of the integration flow in which the TPP establishes an AIS consent and retrieves the PSU’s account list. This flow assumes that

TPP opts for an explicit start of authorization by setting the header Client-Explicit-Authorisation-Preferred: True;
Bank requires Redirect SCA for the initiated transaction.

Note: The flow representation below concentrates on the communication between TPP and the Open Banking Platform's (OBP's) XS2A interface, simplifying the details of OBP-Bank interaction.

Step 1

The Payment Service User (PSU) initiates consent creation via the TPP interface.

Step 2

TPP calls POST /consents/account-access to create AIS consent:

  curl -X POST "https://api.ob.kibs.mk/ais/v2/consents/account-access"
  -H "X-Request-Id: dc7b16a5-4ac8-4fdc-9c4e-9f9d0387dc07"
  -H "Content-Type: application/json"
  -H "PSU-ID: 446456475755"
  -H "PSU-IP-Address: 123.321.123.321"
  -H "Client-Explicit-Authorisation-Preferred: True"
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA.......'
  -d '{
    "access": {
      "payments": [
        {
          "account": {
            "iban": "XX80BANK0000435195001"
          },
          "rights": [
            "accountDetails",
            "balances",
            "transactions"
          ]
        }
      ]
    },
    "consentType": "detailed",
    "recurringIndicator": true,
    "validTo": "2025-12-30",
    "frequencyPerDay": "4"
  }'

Note: If the access right "balances" or "transactions" is used, then the consent on providing "accountDetails" is implicitly given.

Step 3

OBP returns a unique consent ID:

{
  "consentId": "e521cf62-a45f-49c5-8372-94853fffeb55",
  "consentStatus": "received",
  "_links": {
    "startAuthorisation": {
      "href": "/consents/account-access/e521cf62-a45f-49c5-8372-94853fffeb55/authorisations"
    }
  }
}

Step 4

TPP calls POST /consents/account-access/{consent-id}/authorisations (with Client-Redirect-URI and Client-Redirect-Nok-URI headers) to explicitly start authorization (SCA).

Step 5

OBP returns SCA Redirect URL ($.links.scaRedirect.href) for PSU to perform Strong Customer Authentication (SCA):

{
   "scaStatus": "received",
   "authorisationId": "d3f9c3f2-7a8f-4c7f-9b7e-b02e6fdc9420",
   "_links": {
       "self": {
           "href": "/ais/v2/consents/account-access/e521cf62-a45f-49c5-8372-94853fffeb55/authorisations/d3f9c3f2-7a8f-4c7f-9b7e-b02e6fdc9420"
       },
       "scaRedirect": {
            "href": "https://bankscaserver.com/auth/d3f9c3f2-7a8f-4c7f-9b7e-b02e6fdc9420"
       }
   }
}

Step 6

TPP redirects PSU to Bank's SCA Redirect URL. This is a bank's web page where PSU is expected to authenticate and authorize transaction.

Step 7

PSU completes authorization in the bank’s interface (web or mobile).

Steps 8-9

The bank redirects PSU back to TPP using the Client-Redirect-URI provided by TPP.

Step 10

TPP keeps checking consent status until it receives either REJECTED or VALID (GET /consents/account-access/{consent-id}/status).

Step 11

OBP responds with consent status ($.consentStatus):

{
  "consentStatus": "valid"
}

Step 12

TPP informs PSU about the result of consent authorization.

Step 13

PSU requests his/her account information via the TPP interface.

Step 14

TPP calls GET /accounts?withBalance=true with Consent-ID header.

Steps 15-17

OBP verifies that the consent is still valid and requests the data from the Bank.

Step 18

OBP returns the data about PSU's accounts:

{
  "accounts": [
    {
      "iban": "UA80BANK0000435195001",
      "currency": "MKD",
      "resourceId": 12321,
      "name": "string",
      "balances": [
        {
          "balanceAmount": {
            "currency": "MKD",
            "amount": 12.21
          },
          "balanceType": "closingBooked",
          "referenceDate": "12.12.2021"
        }
      ]
    }
  ]
}

Step 19

TPP displays account information to PSU.

AIS-specific error codes

Scenario	Error
Consent that you are trying to use to access your account information is no longer valid.	401 – CONSENT_INVALID
You exceeded the daily limit of 4 GET requests without PSU presence (i.e. requests without `PSU-IP-Address` header)	429 – ACCESS_EXCEEDED