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.
- A
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.
- A
ACCOUNT_BALANCES
andACCOUNT_TRANSACTIONS
- A
Consent
for either or both of these features is a long-livedConsent
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.
- A
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:
POST Create Account Authorisation
Note that the main difference here is that for any
Institution
in this group, the only feature in the response isACCOUNTS_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}}" } }
Authorise the request using the
authorisationUrl
received in the response in step 1Obtain the
consent-token
through thecallback
or by calling GET Consent using the consentid
from the response to Step 1Get 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" } ] } ] }
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 accountACC1
with IBANITXXA
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 featuresACCOUNT_BALANCES
andACCOUNT_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}}" } }
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.
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.
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.
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.
PIS authorisation flow (full payment intiation)
The diagram illustrates full payment authorisation flow if you don't have PRE_AUTHORIZED
consent from the user.