CBI Globe Gateway

Yapily's knowledge article about CBI Globe Gateway

The CBI Globe Gateway allows Italian institutions and other entities to expose their APIs in conformance with the PSD2 directive. Yapily has integrated with the CBI Globe Gateway to allow third parties to connect with Italian institutions.

Coverage

Yapily is connected to following Italian institutions through CBI Globe:

  • Banca Nazionale del Lavoro S.p.A. (BNL)
  • Banca Popolare dell Alto Adige Personal
  • Banca Popolare dell Alto Adige Corporate
  • Banco BPM S.p.A
  • Banco di Sardegna S.p.A.
  • Banca Monte dei Paschi Business
  • Banca Monte dei Paschi Personal
  • Hello Bank!
  • Intesa Sanpaolo S.p.A
  • Posta Italiane (BancoPosta)
  • Unione di Banche Italiane S.p.A. (UBI Banca)
  • Widiba

For each of these banks the consents have different restrictions that you should be aware of when requesting a user's financial data.

Features

For banks listed in the CBI Globe Gateway there are other conditional properties that must be supplied in order when executing POST Create Account Authorisation to retrieve financial data. The only features that can be obtained from banks connected through the CBI Globe Gateway are:

  • ACCOUNT_WITHOUT_BALANCE

    • A Consent created for this feature can only be used once to obtain the account details from an account that the user has authorised.
    • The account balance will not be in the response.
  • ACCOUNTS_WITHOUT_BALANCE

    • A Consent created for this feature can only be used once to obtain the account details from all accounts that the user has authorised.
    • The account balances will not be in the response.
  • ACCOUNT_BALANCES and ACCOUNT_TRANSACTIONS

    • A Consent for either or both of these features is a long-lived Consent that can be used multiple times.
    • A Consent for either or both of these features can also be used to get transactions and/or balances from multiple accounts that the user has authorised.

Note: For each of these features, with the exception of ACCOUNT_BALANCES and ACCOUNT_TRANSACTIONS which can be requested for in a single authorisation, your users will need to individually authorise each of the features. This also means that the associated Consent will only contain a featureScope containing the one feature with the exception of ACCOUNT_BALANCES and ACCOUNT_TRANSACTIONS which can both be accessed using the same Consent. As a consequence, you should verify that the Consent has the right scope in order to access the feature you request as they are not interchangeable. To specify which type of Consent to request from the user, see the request fields below. The CBI Globe enforces the constraint that a TPP can not have more than 1 valid long-lived Consent at any time for a given PSU. As a Consent becomes valid only after a successful completion of the SCA, at that moment any other long-lived Consent will be replaced by the new one.

Restrictions

The CBI Globe defines the following constraint about long running consents: a TPP can't have more than 1 valid recurring consent at a time for a given PSU. Since a consent becomes valid only after the SCA is completed successfully, at that moment any other existing long running consent for that same PSU, will be replaced by the new one.

Account Authorisation Flow

The account authorisation flow for an Institution connected through the CBI Globe differs quite significantly from the Coupled Account Authorisation Flow and is detailed below:

  1. POST Create Account Authorisation

    Note that the main difference here is that for any Institution in this group, the only feature in the response is ACCOUNTS_WITHOUT_BALANCE:

    Example Request Body

    {
        "applicationUserId": "{{application-user-id}}",
        "institutionId": "{{institution-id}}",
        "callback": "{{callback-url}}"
    }
    

    Example Response

    {
        "meta": {
            "tracingId": "b13a729c55fc4f528509a457ce4349e4"
        },
        "data": {
            "id": "e5f40edf-beca-4904-a7ec-ee8c8727e2c4",
            "userUuid": "{{user-uuid}}",
            "applicationUserId": "{{application-user-id}}",
            "institutionId": "{{institution-id}}",
            "status": "AWAITING_AUTHORIZATION",
            "createdAt": "2021-05-13T10:31:15.816Z",
            "expiresAt": "2021-08-11T00:00:00Z",
            "timeToExpire": "P89DT13H28M43.81S",
            "featureScope": [
                "ACCOUNTS_WITHOUT_BALANCE"
            ],
            "state": "c4f52d8add734b13b4017f12f5236ee6",
            "institutionConsentId": "2f1f8398-6f22-491b-a741-6e4fff4d8aae",
            "authorisationUrl": "{{authorisation-url}}",
            "qrCodeUrl": "{{qr-code-url}}"
        }
    }
    

  2. Authorise the request using the authorisationUrl received in the response in step 1

  3. Obtain the consent-token through the callback or by calling GET Consent using the consent id from the response to Step 1

  4. Get Accounts (using the consent-token in the header)

    Note that the response does not include any balance data.

    Example Response

    {
        "meta": {
            "tracingId": "614edddd92ac4bab9f8a0f48514fac65",
            "count": 2
        },
        "data": [
            {
                "id": "ACC1",
                "currency": "EUR",
                "usageType": "UNKNOWN",
                "accountIdentifications": [
                    {
                        "type": "IBAN",
                        "identification": "ITXXA"
                    }
                ]
            },
            {
                "id": "ACC2",
                "currency": "EUR",
                "usageType": "UNKNOWN",
                "accountIdentifications": [
                    {
                        "type": "IBAN",
                        "identification": "ITXXB"
                    }
                ]
            }
        ]
    }
    

  5. POST Create Account Authorisation

    You must now create a second authorisation for a specific account received from step 4. See Account Request for more details about what fields are available. Assuming you wanted to create a Consent that could access both balance information and transaction information for the account ACC1 with IBAN ITXXA from step 4, you would send the following payload:

    Example Request Body

    {
        "applicationUserId": "{{application-user-id}}",
        "institutionId": "{{institution-id}}",
        "callback": "{{callback-url}}",
        "accountRequest": {
            "accountIdentifiersForTransaction": [
                {
                    "accountId": "ACC1",
                    "accountIdentification": {
                        "type": "IBAN",
                        "identification": "ITXXA"
                    }
                }
            ],
            "accountIdentifiersForBalance": [
                {
                    "accountId": "ACC1",
                    "accountIdentification": {
                        "type": "IBAN",
                        "identification": "ITXXB"
                    }
                }
            ]
        }
    }
    

    Note that the response here is for a new Consent that will exclusively have the ability to access the balances and transactions of the user with the features ACCOUNT_BALANCES and ACCOUNT_TRANSACTIONS:

    Example Response

    {
        "meta": {
            "tracingId": "5a03b7e9085e4900b82565614dd41427"
        },
        "data": {
            "id": "16310bc8-8ed5-4d03-a94d-3fdca6a62252",
            "userUuid": "{{user-uuid}}",
            "applicationUserId": "{{application-user-id}}",
            "institutionId": "{{institution-id}}",
            "status": "AWAITING_AUTHORIZATION",
            "createdAt": "2021-05-13T10:51:53.830Z",
            "expiresAt": "2021-08-11T00:00:00Z",
            "timeToExpire": "P89DT13H8M5.692S",
            "featureScope": [
                "ACCOUNT_BALANCES",
                "ACCOUNT_TRANSACTIONS"
            ],
            "state": "44b4269174e647be9ef7f86b3def771c",
            "institutionConsentId": "1ccf37f4-6970-4f9a-9184-59018f14ad8b",
            "authorisationUrl": "{{authorisation-url}}",
            "qrCodeUrl": "{{qr-code-url}}"
        }
    }
    

  6. GET Account Balances (using the second consent-token in the header)

    You must use this endpoint as opposed to GET Accounts to retrieve information about the balance for the appropriate account.

  7. GET Transactions (using the second consent-token in the header)

Historical Data

To get historical transactions older than 90 days, an additional consent is needed from the PSU. In the POST Create Account Authorisation use the transactionFrom and transactionTo fields from AccountRequest to specify the dates you would like to retrieve transactions for. Once the Consent is authorised, the consentToken can be used to retrieve the transactions for this period.

{
    "applicationUserId": "{{application-user-id}}",
    "institutionId": "{{institution-id}}",
    "callback": "{{callback-url}}",
    "accountRequest": {
        "accountIdentifiersForTransaction": [
            {
                "accountId": "ACC1",
                "accountIdentification": {
                    "type": "IBAN",
                    "identification": "ITXXA"
                }
            },
            {
                "accountId": "ACC2",
                "accountIdentification": {
                    "type": "IBAN",
                    "identification": "ITXXB"
                }
            }
        ],
        "transactionFrom": "2020-01-01T00:00:00Z",
        "transactionTo": "2021-01-01T00:00:00Z"
    }
}

Note: This consentToken (that can access historical data older than 90 days) can only be used once. If you need to retrieve transactions older than 90 days, again, you must follow the same process again to create a new one-time use Consent.