Access To Accounts

Overview

The Account Information Service (AIS) enables TPPs to access account information of a Payment Service User (PSU). To access account information, the TPP must first obtain authorization (consent approval) from the PSU. With the approved consent, the TPPs can retrieve essential account information including balances, transaction history, and other pertinent details.

Request Scenario

In the following scenario, we present a the process for accessing account list. Initially, the TPP must secure consent from the Payment Service User (PSU) to access their data. Once the PSU grants consent at the interface of the ASPSP, the TPP is then authorized to proceed with making a request for account list retrieval.

Step 1. PSU Initiates Account Access

The Payment Service User (PSU) initiates access to their account information through the TPP interface.

Step 2. Account Information Consent Request

In this initial step, using an access token that was previously acquired, the TPP initiates an account information consent request to obtain the PSU's approval for accessing their account information.

To establish an account information consent, the TPP must make “Establish Consent Transaction” request to /consents endpoint:

POST

/xs2a/v1.3/consents

Request example

  curl --location 'https://api.ob.stb.kibs.mk/xs2a/v1.3/consents'
  --header 'Obp-Sandbox-Environment: true'
  --header 'X-Request-ID: a314dc55-3acc-44f1-baad-ac117fff4ea0'
  --header 'TPP-Redirect-URI: https://tpp-success-page'
  --header 'Content-Type: application/json'
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cC....'
  --data'{
   "access": {
      "accounts": [],
      "balances": [],
      "transactions": []
   },
   "combinedServiceIndicator": "false",
   "frequencyPerDay": "100",
   "recurringIndicator": "true",
   "validUntil": "2023-08-26",
}

Note: Important to note that the value of header TPP-Redirect-URI indicates the address to which the ASPSP will redirect the PSU after consent approval.

Step 3: ASPSP Sends Back Error Message (If Request Fails)

If the account information consent request encounters an issue, the ASPSP (Account Servicing Payment Service Provider) responds with an appropriate error message.

Step 4: ASPSP Sends Back an Authorization Link (If Request Is Successful)

Upon a successful account information consent request, the ASPSP replies with an authorization link to the TPP.

Response example

{
 "consentStatus": "received",
 "consentId": "49e10c1a-31fb-4ee7-b0f3-efa72073df27",
 "_links": {
    "self": {
       "href": "/xs2a/1.3.0/consents/49e10c1a-31fb-4ee7-b0f3-efa72073df27"
    },
    "status": {
       "href": "/xs2a/1.3.0/consents/49e10c1a-31fb-4ee7-b0f3-efa72073df27/status"
    },
    "scaRedirect": {
       "href": "https://bank-sca-page/sca-client/mock/2b7d34a0-2baa-40ef-91d2-32708b9b0ae0/consent"
    }
 },
 "authorisationId": "2b7d34a0-2baa-40ef-91d2-32708b9b0ae0",
 "tppMessages": [
   {
    "category": "MSG",
    "code": "INFO",
    "text": "Go to authorization url!"
   }
 ]
}

Step 5: TPP Redirects PSU to Authorization Link to Authorize Consent

The TPP guides the PSU to the authorization link, necessary for consent approval by the PSU.

Step 6: PSU Authorizes Consent

Upon accessing the authorization link, the PSU provides consent to the TPP for accessing their account information data within the interface of the ASPSP.

Step 7: ASPSP Redirects PSU to TPP Interface

Following consent approval, the ASPSP redirects the PSU back to the interface of the TPP.

Step 8: Redirect to Failed Consent Approval Interface

If the PSU declines consent approval or fails to do it, they are redirected to the TPP's failed consent approval interface - TPP-Nok-Redirect-URI or TPP-Redirect-URI header’s value if Nok URI is not present.

Step 9: Redirect to Successful Consent Interface

If the PSU approves the consent, they are directed to the TPP's successful consent interface, signifying successful authorization - TPP-Redirect-URI header’s value.

Step 10. Verify consent status.

Optionally, the TPP can proceed with consent status verification. This verification process ensures that the consent request has been properly received and processed by the PSU's ASPSP. By confirming the consent status, the TPP can accurately determine whether they are authorized to proceed with accessing the requested account data.

To verify consent status, the TPP must make a “Get Status” request to consents/{consent-id}/status endpoint:

Request example

curl --location 'https://api.ob.stb.kibs.mk/xs2a/v1.3/consents/49e10c1a-31fb-4ee7-b0f3-efa72073df27/status'
--header 'Obp-Sandbox-Environment: true'
--header 'X-Request-ID: d13de9ff-9485-44b3-8374-f68de7b1dce3'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA.......'

Step 11: ASPSP Sends Consent Status to TPP

In response to the TPP's request, the ASPSP provides the current consent status.

Step 12. Retrieve Account List

Once the previously established consent has been successfully approved by the PSU, the TPP receives a unique consent ID as part of the confirmation process. This consent ID, obtained through the "Establish Consent Transaction" request, serves as a the means that allows to retrieve the PSU's account list.

To retrieve account list, the TPP must make a “Read Account List” request to /accounts endpoint:

GET

/xs2a/v1.3/accounts

Request example

curl --location 'https://api.ob.stb.kibs.mk/xs2a/v1.3/accounts'
--header 'Obp-Sandbox-Environment: true'
--header 'X-Request-ID: 5bfa8e2e-359c-4bb1-8a39-60e6c77c21da'
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJfTEh2RjlJMDBDM1Jv.....'
--header 'Consent-ID: 49e10c1a-31fb-4ee7-b0f3-efa72073df27'

Step 13: ASPSP Sends Back Error Message

Should the consent have expired or the account information request encounter an issue, the ASPSP responds with an appropriate error message.

Step 14: ASPSP Responds With Account List

If the account information request is successful, the ASPSP responds with the requested account data, namely the account list.

Step 15: TPP Shows Account Data in TPP Interface

The TPP displays the PSU's account list, in its interface, completing the account information retrieval process.