How to call our APIs

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

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.

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.mediobancapremier.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.mediobancapremier.io

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

Example request:

GET/POST/PUT/DELETE https://external-api.mediobancapremier.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

The accounts API returns the list of accounts of the customer.

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_NICKNAME>"
            }
            ....
        ]
    },
    "result": {
        "requestId": "<REQUEST_UNIQUE_ID>",
        "outcome": "SUCCESS",
        "flushMessages": true,
        "messages": []
    },
    "_links": {
        "self": {
            "href": " ",
            "method": "GET"
        },
        "curies": [
            {
                "href": "https://external-api.mediobancapremier.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 PIISP or a PISP
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)

Important note: the consent given for a specific account is valid forever until explicitly revoked by the customer, so this is an operation to be performed usually only on the first access.

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.mediobancapremier.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.mediobancapremier.com/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.mediobancapremier.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

For inquiry APIs, you should take a look at this page to understand the process to follow in case of PSD2_SCA_REQUIRED error code.

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.