Access To Accounts

Overview

The Funds Confirmation Service (PIIS) allows Third-Party Providers (TPPs) to verify avaialble funds on accounts of the Payment Service User (PSU). To access the funds availability information, TPP must create a funds confirmation consent and have it approved by PSU. With the approved consent, TPP can check balance of a particular account before initiating a credit transfer.

Flow description

Below is the description of the integration flow in which the TPP establishes a PIIS consent and verifies the availability of funds for a particular account of a PSU. 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/funds-confirmations to create AIS consent:

  curl -X POST "https://api.ob.kibs.mk/ais/v2/consents/funds-confirmations"
  -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": [
            "fundsConfirmations"
          ]
        }
      ]
    },
    "consentType": "detailed",
    "recurringIndicator": true,
    "validTo": "2025-12-30",
    "frequencyPerDay": "4"
  }'

Step 3

OBP returns a unique consent ID:

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

Step 4

TPP calls POST /consents/funds-confirmations/{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/funds-confirmations/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/funds-confirmations/{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 initiates payment.

Step 14

Before payment initiation TPP decides to check the availability of funds on debtor's account and calls POST /funds-confirmations with Consent-ID header:

{
  "account": {
    "iban": "XX80BANK0000435195001",
    "currency": "MKD"
  },
  "payee": "customer name",
  "instructedAmount": {
    "currency": "MKD",
    "amount": "12.32"
  }
}

Steps 15-17

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

Step 18

OBP returns the result of funds availability check:

{
   "fundsAvailable": true
}

Step 19

TPP proceeds to payment initiation.

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