Skip to main content

Account

For both TPP and FPP the response obtained following a request for accounts is exactly the same and is described below. The request APIs instead vary slightly and you can refer to the related documentation for implementation details.

The response will be an array of accounts and each element is like the following sample:

{
    "accountId": "1243",
    "bankId": "2",
    "bankProfileId": "132",
    "userId": "12",
    "alias": null,
    "bicCode": "ABXXXXXX",
    "cashType": null,
    "currency": "EUR",
    "deletedDatetime": null,
    "details": "",
    "displayName": "",
    "isDeleted": false,
    "consentEndDateTime": "2023-01-01T22:59:59.000+0000",
    "consentStatus": "VALID",
    "lastBalances": [{
        "amount": {
            "currency": "EUR",
            "value": 0
        },
        "amountInEuro": {
            "currency": "EUR",
            "value": 0
        },
        "balanceId": "",
        "balancePriority": 0,
        "balanceTimePeriod": "",
        "balanceType": "",
        "deletedDatetime": "2021-06-14T09:25:14.605Z",
        "exchangeRate": 0,
        "isCreditLimitIncluded": true,
        "lastChangeDatetime": "2021-06-14T09:25:14.605Z",
        "lastCommittedTransaction": "",
        "referenceDate": "2021-06-14T09:25:14.605Z",
        "retrievedDatetime": "2021-06-14T09:25:14.605Z",
        "type": ""
    }],
    "lastUpdatedDatetime": "2019-09-15T09:00:01.000Z",
    "linkedAccounts": null,
    "name": null,
    "ownerName": "MARIO ROSSI",
    "productName": "STANDARD PERSONAL CASH ACCOUNT",
    "reference": null,
    "retrievedDatetime": "2019-09-14T09:14:12.000Z",
    "subsidiaryValues": [{
        "currency": "EUR",
        "reference": null,
        "value": "IT32FXXXXXYYYYYKKKKKKKKKKKK",
        "valueType": "IBAN"
    }],
    "synchronizationStatus": {
        "balances": {
            "hasActiveConsent": true,
            "isSynchronized": true,
            "lastSynchronizedDatetime": "2019-09-15T09:00:01.000Z",
            "wasInLastConsent": true
        },
        "transactions": {
            "hasActiveConsent": true,
            "isSynchronized": true,
            "lastSynchronizedDatetime": "2019-09-15T09:00:03.000Z",
            "wasInLastConsent": true
        }
    },
    "tppUid": "100000",
    "usage": "PERSONAL",
    "value": "IT32FXXXXXYYYYYKKKKKKKKKKKK",
    "valueType": "IBAN"
}

Each element of the list indicates a user account and it contains information relating to the account, the user and a series of outline information added by Fabrick that enrich the model:

  • accountId: indicates the unique id of the account set up by Fabrick

  • bankId: indicates the unique id of the bank

  • bankProfileId: for TPP only, indicates the unique id of the bankProfile

  • userId: indicates the unique id of the user

  • alias: optional string that can be used by the end user (via the TPP or FPP) to set a custom alias for the account in question

  • bicCode: indicates the BIC code

  • cashType: to be ignored. It is the ISO 20022 Code (ExternalCashAccountType1Code - https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets), but it is not returned.

  • currency: represents the local currency of the account. For example se the account is in EUR the value will be in EUR. If the account is in another currency, the value corresponding to the account's local currency will be entered. (Fineco for example will have multiple accounts with different currencies)

  • details: represents the specificities of a particular account, for example: characteristics of an account or a card. To date, it is almost never retuned from banks

  • displayName: account name defined by the user within the Online Banking channel. In most cases, the field is not present

  • consentEndDateTime: indicates the expiration date of the consent associated with this account

  • consentStatus: indicates the consent status (see consent details for values)

  • lastBalances: provides information on the balance (see the Balance Details document for more information on object parameters)

  • lastUpdatedDatetime: last update of the account element, or in other words indicates the date of the last synchronization with the ASPSP, for example when an account refresh is performed from TPP. The first time the account is retrieved from the bank this date will coincide with the retrieveDatetime field

  • linkedAccounts: field where the ASPSP can enter the name of the account (in cash) associated with the main account for pending transactions of a given card

  • name: account name, assigned by the ASPSP

  • ownerName: name of the account holder

  • productName: name of the account, as appointed by the Bank. The definition is proprietary. and then the value depends on the final bank

  • reference: account identifier.

  • retrievedDatetime: date on which information for a particular account was retrieved

  • subsidiaryValues: Only for TPP (not for FPP currently) it is possible to aggregate cards too. In the case of a card with an IBAN, the subsidiaryValues carrier must be considered, which will contain several value - valueType pairs as shown in the example:

    ...
    "subsidiaryValues": [
      {
        "value": "IT00A12345678000AA000123456",
        "valueType": "IBAN"
      },
      {
        "value": "1234 xxxx xxxx 5678",
        "valueType": "MASKED_PAN"
      }
    ],
    ...

    A particular example could be Hype where, by invoking the GET Get Account, we will get an IBAN in response, and by invoking the GET Get Card we will get a maskedPan; in both cases we will obviously have the same balance and the same movements.

  • synchronizationStatus: indicates the status of the balances and movements of that account through the following parameters:

    • hasActiveConsent: is a boolean that indicates, at the time of the request, se there is an active consent for the parts of balances and transactions respectively - isSyncronized: this boolean indicates se the entity should be automatically synchronized by Fabrick or not. Only for TPP it can be set via the PUT Update Account and PUT Update Card endpoints.
    • lastSynchronizedDatetime: indicates the date and time of the last synchronization of balances and transactions respectively.

  • wasInLastConsent: this boolean is true se the entity was selected during the creation of the last consent currently expired. With this parameter, the TPP can show the same consensus that the PSU had created the last time. This variable obviously cannot be modified by the TPP. The parameter will revert to false when the next authorized consent no longer contains that particular account.

  • tppUid: the TPP id

  • usage: identifies the type of account: PRIVATE (for Retail, Private accounts), BUSINESS (for Company, Corporate accounts)

  • value: indicates the account number or the anonymized card number or a different string in case of different valueType (cards are allowed only for TPP to date)

  • valueType: indicates the type of the account, it can be the IBAN, MASKED_PAN or WALLET (MASKED_PAN is allowed only fot TPP to date). In case of WALLET the parameter value could be an email (for example Paypal) or an ID (for example Revolut).

    In the event that the customer had associated a card with the Paypal account, the balance information returned would be 0, as it would refer to the wallet and not to the associated card. The movement list, on the other hand, is visible but with less information

Balances and transactions scheduler​

The information relating to balances and movements for each consent in VALID status is automatically updated 4 times a day using the unattended accesses allowed by the legislation. Since a maximum of 4 calls per day are possible for each consent and type of request, like Fabrick we preferred to concentrate the synchronization phases during the day, so that the PSU can have the movements always updated in the moments of greatest use of the service:

  1. 08:30: transactions and balances
  2. 11:30: transactions and balances
  3. 14:30: transactions and balances
  4. 17:30: transactions and balances

Obviously these are intended as time slots whose duration is about 90 minutes. This is because banks do not allow high parallelism of calls, so Fabrick is forced to serialize update requests for all individual accounts.