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. If the APIs to call involve the customer information, the only available grant type here is the authorization_code

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.

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>

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.

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: 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 documentation here