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.

Old CBI Globe flow (to be deprecated on 10th of May, 2022)

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.

New CBI Globe flow

Our new GBI Globe flow removes the need for a double redirect when initiating payments. We now capture the unique token for a PSU and allow clients to use this token during the payment auth request call.

This improves the reliability of integrations with banks that use the CBI Globe API.

The payment authorisation process is easier, since PSUs do not need to complete weak authentication (username + password) steps twice per payment.

Why is the change happening?

To allow for a more normalised flow for those IT banks that are supported by the CBI Globe API.

Identifying the flow

CBI Globe institutions are using either one-time pre-authorisation or embedded flow:

  • Institutions that follow CBI Globe one-time authorisation flow will contain INITIATE_ONETIME_PRE_AUTHORISATION_PAYMENTS feature
  • Institutions that follow the embedded flow will have one of the initiate payment features, for example INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT

Financial data

Our current implementation for these banks requires a consent for getting account details and a separate consent for getting balances and transactions (using those account details). With the new AIS flow, customers will be able to obtain account details, balances and transactions consent via a single consent. This is more similar to single redirect flow as used by Commerzbank, Unicredit, Fineco etc.

There is a limitation that customers can only call GET /accounts once per consent. Customers should store the account id to be able to GET /balances and GET /transactions.

AIS authorisation flow

Financial data can be accessed by following our standard single redirect flow, although keep in mind that you can call GET /accounts only once per consent so consider storing account details.

Authorisation_Flows-1L_Default_Accounts

Payments

Yapily’s current payments flow relies on a double redirect method to initiate weak authentication and follow up with a SCA authentication. While technically valid,the CBI Globe API was found to be too unreliable for this flow.

The new PIS flow involves obtaining a one-time pre-authorisation consent for a PSU and this may be used multiple times (with no expiry) for that PSU to initiate payments. The pre-authorisation also involves initiating a payment - for security purposes - that will never be completed (therefore never charged to the payer).

Customers should use a static IBAN and a small amount (€0.01) for this pre-authorisation payment. Once pre-authorisation is obtained, customers can initiate a real payment through to completion.

PIS pre-authorisation flow (once per user)

Initiate pre-authorisation flow illustrated below once per user to receive a permanent consentToken. The consent will stay under PRE_AUTHORIZED status and can be used multiple times to initiate payments, therefore, consider saving consentToken for future payments.

Authorisation_Flows-cbi-one-time

PIS authorisation flow (initiating payment for existing user)

If you already have a consentToken from the pre-authorisation step, you can initiate a payment by following the diagram below.

Authorisation_Flows-cbi-payment-auth

PIS authorisation flow (full payment intiation)

The diagram illustrates full payment authorisation flow if you don't have PRE_AUTHORIZED consent from the user.

Authorisation_Flows-cbi-full-flow