How to call our APIs


You can call CheBanca! APIs on external-api.chebanca.io domain. As a prerequisite, you should already have requested an Application in the Profile private section in the portal.

OAuth login

It's the standard OAuth 2.0 authentication flow.

At the end of the flow, the caller application server will obtain the OAuth access token, which will grant access to all the configured APIs.

See also OAuth2.0 - Flows

Headers

See also Headers&Cookies for details about the requested headers.

PSD2 specific headers

To implement the Payment Service Directive 2 (PSD2) we require the AISP/PISP to insert some specific headers in every API call. Following a short description:

Header name Description
Authorization It contains the security token (Bearer < OAuth access token >)
TPP-Transaction-ID Id of the entire transaction, determined by the TPP
TPP-Request-ID Id of the single API request, determined by the TPP
TPP-Certificate It contains the TPP certificate used to sign the HTTP request
Signature Signature of the request, as defined in draft-cavage-http-signatures-09
Digest SHA256 of the request body
Date Header containing the date and time of the request. It follows the RFC 7231 Full Dates specification

These headers are also documented in each API reference.

You must pass these headers in every API request to external-api.chebanca.io (in the following sections, for readability, the specific PSD2 headers will be omitted, but they have to be added in order to perform a real call).

Requests to external-api.chebanca.io

First of all, you need an OAuth2.0 access token (see here).

Example request:

GET/POST/PUT/DELETE https://external-api.chebanca.io/path/to/api

Headers:
    Accept: application/json
    Content-Type: application/json
    CB-Trace-Id: viewId=<NAME_OF_CALLER_COMPONENT>
    Accept-Language: <YOUR_LANGUAGE>
    cb-apitrack-id: <CB_APITRACK_ID>
    Authorization: Bearer <OAUTH_ACCESS_TOKEN>
    TPP-Request-ID: <TPP_REQUEST_ID>
    TPP-Certificate: <TPP_CERTIFICATE>
    Signature: <SIGNATURE>
    Digest: <DIGEST>
    Date: <REQUEST_DATE>
Body:
{
    json structure
}

Access Control Lists (ACL)

A client application is subject to a set of ACL. Based on the third party PSD2 profile (AISP/PISP), when you request an application the ACLs will automatically be created. Basically, if you're an AISP, the ACLs will allow you to call only inquiry APIs, while if you're a PISP you will be allowed to call payment APIs.

If the application is requested for the Sandbox environment no ACL will be checked at runtime.

Required API Flow to obtain customer information

There is a fixed flow of operations to execute to obtain customer data and execute operations on his behalf. Note that the PSD2 headers will be omitted from the example for readability.

Step 1: Authentication

The login phase is explained here

Step 2: Get customer identifier

Call this API to get the identifier of the authenticated customer

GET /private/customers/customerid-info
Headers
    Accept: application/json
    Content-Type: application/json
    CB-Trace-Id: viewId=<NAME_OF_CALLER_COMPONENT>
    Accept-Language: <YOUR_LANGUAGE>
    cb-apitrack-id: <CB_APITRACK_ID>
    Authorization: Bearer <OAUTH_ACCESS_TOKEN>
{
    "data": {
        "customerid": "<CUSTOMER_ID>"
    },
    "result": {
        "result": true,
        "requestId": "<REQUEST_UNIQUE_ID>",
        "outcome": "SUCCESS",
        "flushMessages": true,
        "messages": []
    }
} 

Step 3: Get customer accounts

GET /private/customers/{customerId}/accounts
Headers
    Accept: application/json
    Content-Type: application/json
    CB-Trace-Id: viewId=<NAME_OF_CALLER_COMPONENT>
    Accept-Language: <YOUR_LANGUAGE>
    cb-apitrack-id: <CB_APITRACK_ID>
    Authorization: Bearer <OAUTH_ACCESS_TOKEN>
{
    "data": {
        "accounts": [
            {
                "accountId": "<PRODUCT_ID>",
                "product": {
                    "code": "<PRODUCT_TYPE_CODE>",
                    "description": "<PRODUCT_TYPE_DESCRIPTION>"
                },
                "currency": "<CURRENCY>",
                "iban": "<IBAN>",
                "name": "<PRODUCT_NICKAME>"
            }
            ....
        ]
    },
    "result": {
        "requestId": "<REQUEST_UNIQUE_ID>",
        "outcome": "SUCCESS",
        "flushMessages": true,
        "messages": []
    },
    "_links": {
        "self": {
            "href": " ",
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://external-api.chebanca.io/private/customers/3610569/accounts/{rel}",
                "name": "accounts"
            }
        ]
    },
    "_embedded": {}
}

Step 4: Grant Consent

This step is required only the first time the customer logs in the TPP application or in case of modification to the given consent. You must specify a list of API categories you want the access to, and for each one a list of customer products (identified by a productId, returned by the /accounts API) that will be given the consent on. The possible API categories you can request access to are:

  • ACCOUNT_INFO -> if you're an AISP
  • FUNDS_AVAILABILITY -> if you're a CISP
  • PAYMENTS -> if you're a PISP

The consent workflow consists of 3 steps:

  • a consent request, with all the required details
  • the authentication workflow, started by the /private/auth/security/sca/{resourceId}/approach API
  • the consent request confirmation, after a successful customer authentication

In production, you can have a client_credentials application in addition to your authorization_code application. The consent can be given only with the user online, so you need to call the API to grant consent with the authorization_code client. The privileges will be automatically propagated to your client_credentials application. So, if a customer gives you the privilege to get the balance of his account n. 123456, you can read his balance both with your authorization_code application and with your client_credentials application (with the PSD2 directive limitations)

Consent request
POST /private/customers/{customerId}/consent/request
Headers
    Accept: application/json
    Content-Type: application/json
    CB-Trace-Id: viewId=<NAME_OF_CALLER_COMPONENT>
    Accept-Language: <YOUR_LANGUAGE>
    cb-apitrack-id: <CB_APITRACK_ID>
    Authorization: Bearer <OAUTH_ACCESS_TOKEN>
Request:
{
    "data": {
        "categories": [
            {
              "name": "ACCOUNT_INFO",
              "products": [
                "0001922365",
                "0012558963"
              ]
            },
            {
              "name": "PAYMENTS",
              "products": [
                "0001922365",
                "0012558963"
              ]
            }
          ]
    }
}
Response:
{
    "data": {
        "categoriesOutcome": [
            {
                "name": "ACCOUNT_INFO",
                "outcome": true
            },
            {
                "name": "PAYMENTS",
                "outcome": true
            }
        ]
    },
    "result": {
        "requestId": "<REQUEST_UNIQUE_ID>",
        "outcome": "SUCCESS",
        "flushMessages": true,
        "messages": []
    },
    "_links": {
        "next": {
            "href": "request/24ab6f20-24ff-403d-871c-f30de0d2802a/confirm",
            "method": "PUT"
        },
        "self": {
            "href": "request",
            "method": "POST"
        },
        "curies": [
            {
                "href": "https://external-api.chebanca.io/private/customers/<CUSTOMER_ID>/consent/{rel}",
                "name": "consent"
            }
        ]
    },
    "_embedded": {},
    "resources": {
        "resourceId": "24ab6f20-24ff-403d-871c-f30de0d2802a"
    }
}
Consent authorization
GET /private/auth/security/sca/{resourceId}/approach
Headers
    Accept: application/json
    Content-Type: application/json
    CB-Trace-Id: viewId=<NAME_OF_CALLER_COMPONENT>
    Accept-Language: <YOUR_LANGUAGE>
    cb-apitrack-id: <CB_APITRACK_ID>
    Authorization: Bearer <OAUTH_ACCESS_TOKEN>
    TPP-Redirect-URI: <TPP_CALLBACK_AFTER_SCA>
Response:
{
  "resources": {
    "resourceId": "24ab6f20-24ff-403d-871c-f30de0d2802a"
  },
  "result": {
        "requestId": "<REQUEST_UNIQUE_ID>",
        "outcome": "SUCCESS",
        "flushMessages": true,
        "messages": []
   },
   "_links": {},
   "_embedded": {},
   "data": {
       "scaRedirectURL": "https://clienti.chebanca.it/sca-authorize/?resourceId=<RESOURCE_ID>",
       "chosenScaApproach": "REDIRECT"
   }
}

Then, the TPP must return to the browser a redirect to the scaRedirectURL returned by the previous API. The customer will be in charge of completing the SCA in the browser, and at the end the customer will be redirected to < TPP_CALLBACK_AFTER_SCA >, which is a TPP resource. After that, TPP will be able to call the confirmation API.

Consent confirmation
PUT private/customers/{customerId}/consent/request/{resourceId}/confirm
Headers
    Accept: application/json
    Content-Type: application/json
    CB-Trace-Id: viewId=<NAME_OF_CALLER_COMPONENT>
    Accept-Language: <YOUR_LANGUAGE>
    cb-apitrack-id: <CB_APITRACK_ID>
    Authorization: Bearer <OAUTH_ACCESS_TOKEN>
Request:
{}
Response:
{
    "data": {},
    "result": {
        "requestId": "<REQUEST_UNIQUE_ID>",
        "outcome": "SUCCESS",
        "flushMessages": true,
        "messages": []
    },
    "_links": {
        "self": {
            "href": "request/24ab6f20-24ff-403d-871c-f30de0d2802a/confirm",
            "method": "POST"
        },
        "curies": [
            {
                "href": "https://external-api.chebanca.io/private/customers/<CUSTOMER_ID>/consent/{rel}",
                "name": "consent"
            }
        ]
    },
    "resources": {
        "resourceId": "24ab6f20-24ff-403d-871c-f30de0d2802a"
    }
}

Step 5: Call any other API

Now that you have the authentication token, the customerId and the productId, you can call any other API!

You can find the API reference here

If you want to implement a payment with our APIs, you should also read here, where you can find more information about our payment workflow.