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.

Identifying the flow

An Institution that uses the redirect CBI Globe flow:

  • Will have the INITIATE_ONETIME_PRE_AUTHORISATION_PAYMENTS feature
Note
  • Use GET Institutions to check for each Institution that uses the INITIATE_ONETIME_PRE_AUTHORISATION_PAYMENTS feature

New CBI Globe flow

We deprecated our old CBI Globe flows on 10th May 2022.

Our new CBI Globe flows have simplified both the AIS and PIS flows.

Financial data

Our old CBI Globe AIS flow required a consent for getting account details and a separate consent for getting balances and transactions, using those account details.

With the new AIS flow, you can obtain account details, balances and transactions consent via a single consent. This is more like the single redirect flow as used by Commerzbank, Unicredit, Fineco etc.

AIS authorisation flow

Financial data can be accessed by following our standard single redirect flow.

Authorisation_Flows-1L_Default_Accounts

Request:

Copy
Copied
curl --location --request POST 'https://api.yapily.com/account-auth-requests' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic {authToken}' \
  --data-raw '{
    "applicationUserId": "{{application-user-id}}",
    "institutionId": "{{institution-id}}",
    "callback": "{{callback-url}}",
  }'

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. You can specify a timeframe for up to 1 year. Once the consent is authorised, the consentToken can be used to retrieve the transactions for this period.

Request:

Copy
Copied
curl --location --request POST 'https://api.yapily.com/account-auth-requests' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic {authToken}' \
  --data-raw '{
    "applicationUserId": "{{application-user-id}}",
    "institutionId": "{{institution-id}}",
    "callback": "{{callback-url}}",
    "accountRequest": {
        "transactionFrom": "2021-06-30T00:00:00Z",
        "transactionTo": "2022-06-30T00: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.

Payments

Our old CBI Globe PIS flow used a double redirect method, which could be unreliable when used with the CBI Globe API.

The new PIS flow involves obtaining a one-time pre-authorisation consent for a PSU. This consent can 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

Request:

Copy
Copied
curl --location --request POST 'https://api.yapily.com/payment-auth-requests' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic {authToken}' \
  --data-raw '{
    "institutionId": "{{institution-id}}",
    "applicationUserId": "{{application-user-id}}",
    "callback": "{{callback-url}}",
    "scope": "PIS",
    "amount": {
        "amount": "0.01",
        "currency": "EUR"
    },
    "reference": "Reference",
    "payer": {
        "name": "Name Surname",
        "accountIdentifications": [
            {
                "type": "IBAN",
                "identification": "IT02J0538712900000001617752"
            }
        ]
    },
    "payee": {
        "name": "Name Surname",
        "country": "IT",
        "accountIdentifications": [
            {
                "type": "IBAN",
                "identification": "IT65R0301503200000003400077"
            }
        ]
    }
}'

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

Request:

Copy
Copied
curl --location --request POST 'https://api.yapily.com/payment-auth-requests' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic {authToken}' \
  --header 'Consent: {consentToken}' \
  --data-raw '{
    "institutionId": "{{institution-id}}",
    "applicationUserId": "{{application-user-id}}",
    "callback": "{{callback-url}}",
    "paymentRequest": {
        "type": "DOMESTIC_PAYMENT",
        "reference": "Reference",
        "amount": {
            "amount": 10,
            "currency": "EUR"
        },
        "paymentIdempotencyId": "bJ6MdT42wTOKbRUaGqVFn3E",
        "payee": {
            "name": "Name Surname",
            "address": {
                "country": "IT"
            },
            "accountIdentifications": [
                {
                    "type": "IBAN",
                    "identification": "IT65R0301503200000003400077"
                }
            ]
        },
        "payer": {
            "name": "Name Surname",
            "accountIdentifications": [
                {
                    "type": "IBAN",
                    "identification": "IT02J0538712900000001617752"
                }
            ]
        }
    }
}'

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