Skip to content

TPP On Boarding

In these section we describe the procedure that enables a TPP who wants deliver payment initiation services or account information services to A-Tono Payment Institute users, to access the dedicated API.

The procedure goes through three phases:

  1. registration, to be performed once
  2. authentication, to be performed every time a new access session must be activated
  3. resource access, that represent the API method invocation in itself
graph LR C(Registration) --> Au(Authentication) Au --> Ac(Resource Access)

Registration

The Registration phase is needed to record in DropPay systems the authorization number referred to in para 2 of article 34 of COMMISSION DELEGATED REGULATION (EU) 2018/389 of 27 November 2017 ad to link it the TPP owned authorizations, extracted from ABE registry referred to in article 15 of DIRECTIVE (EU) 2015/2366 OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL of 25 November 2015

To accomplish that the TPP must have a qualified eIDAS QWAC certificate released by an european widely known QTSP which is registered by ABE as stated by para 4 of article 22 of REGULATION (EU) No 910/2014 OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL of 23 July 2014

TPP must call once the self-service API

https://api.drop-pay.io/auth/realms/droppay/tpp/register

using POST method whose body must contain an empty JSON object

1
    {}
and using TLS protocol authentication with its eIDAS certificate:

sequenceDiagram participant T as TPP participant S as DropPay T->>S: Request over HTTPS Note over T,S: POST /auth/realms/droppay/tpp/register Note over T,S: {} S-->>T: Response Note over T,S: Status Code = 204, 200 or 4xx
The response received will be alternatively one of the following ones:

  • an empty body and a HTTP Status Code 204 as successful operation;
  • a JSON object that
    • is containing extended data useful to fulfill the registration phase and a 200 HTTP Status Code (this case is not yet implemented)
    • is containing an error object as the one showed below and a HTTP Status Code 4xxor 5xx as failure operation
1
2
3
4
5
6
{
  "error": {
    "code": 101,
    "description": "not a qualified certificate"
  }
}

Possible errors are:

  • expired certificate or invalid certificate;
  • TPP is missing authorization to operate in Italy;
  • TPP is already registered;

Warning

For some error types, like expired certificate or certificate signed by an unknown QTSP, the communication may fail at TLS protocol handshake time, that is before client and server have the chance to exchange HTTP messages.

If that is happening please contact us at psd2-tpp@drop-pay.com and describe the issue you are facing.

Please remember that, as long as the TPP is identified by the authorization number issued by her own national authority, when an eIDAS certificate is renewed, the registration phase won't need to be repeated.

Authentication

A successful Authentication phase results with an useful user's account working session.

The session is identified by an "access token" which must be used in every subsequent API call.

In order to obtain the Access Token an HTTP POST request must be send to:

https://api.drop-pay.io/auth/realms/droppay/protocol/openid-connect/token

with the following parameters:

  • grant_type=password
  • username valued with user name (a valid Italian MSISDN)
  • password valued with user's password

Italian MSISDN

An "Italian MSISDN" is a mobile phone number compliant with ITU.T E.164 format, with international prefix 39 (Italy) but without and selector prefix like 00, +, etc. A valid MSISDN is for example 393351234567

The client-server connection must be established by TLS protocol along with use of eIDAS certificate.

sequenceDiagram participant T as TPP participant S as DropPay T->>S: Request over HTTPS Note over T,S: POST /auth/realms/droppay/protocol/openid-connect/token Note over T,S: grant_type=password username=393331234567 password=somesecrettoken S-->>T: Response Note over T,S: Status Code = 200 or 4xx

In case of successful authentication, the response is containing a json object, like the following one:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "access_token": "eyJhbGciOi...DsMCHs09og",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOi...rPmNR4Xn5E",
  "token_type": "bearer",
  "not-before-policy": 1533282000,
  "session_state": "04293183-cbba-42ca-9187-edce59a8c22e",
  "scope":"tpp"
}

If an error is returned, a different JSON object will be found in the response body, containing a description of the problem:

1
2
3
4
{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}

Access Token life time is set to 5 minutes (300 seconds). Once it expires a new one must be requested. For that purpose a refresh token, along with access token, is delivered too.

To obtain a new access token, a HTTP POST request must be send to:

https://api.drop-pay.io/auth/realms/droppay/protocol/openid-connect/token

with the following parameters:

  • grant_type=refresh_token
  • refresh_token valued with refresh token
sequenceDiagram participant T as TPP participant S as DropPay T->>S: Request over HTTPS Note over T,S: POST /auth/realms/droppay/protocol/openid-connect/token Note over T,S: grant_type=refresh_token refresh_token=eyJhbGciOi...rPmNR4Xn5E S-->>T: Response Note over T,S: Status Code = 200 or 4xx

The response content is identical to the one described above.

The Refresh Token expires after 30 minutes (1800 seconds). If that happens a fresh new Access Token must be requested passing in again user's credentials.

Otherwise if the Refresh Token is continued to be used a session hard expiration limit is set to 10 hours.

More details on json object exchanged during the authentication phase can be found in sections 4.3 and 5 of OAuth 2.0 Technical Specification (Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012).

Client Authetication

The TPP client is not requested to value parameters as client_id and client_secret in the requests bodies or in any other HTTP header. Actually identification is accomplished using eIDAS certificate used to establish the HTTPS communication.

Resource Access

Access Token - JWT format

The Access Token is a valid JWT (https://jwt.io/) and, once decoded, it brings all the folowing informations :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
- header: {
   "alg": "RS256",
   "typ": "JWT",
   "kid": "DJdfAXaCnYNxgTNeYQp0bwzJhbIJqLUH9gpunRmCNvw"
 }
- body: {
   "jti": "7c9bd8c2-edb1-45fb-a1a4-6c4090d36251",
   "exp": 1555337307,
   "nbf": 0,
   "iat": 1555337007,
   "iss": "https://api.drop-pay.io/auth/realms/droppay",
   "sub": "f:fb05e6a5-e3db-44e7-9e9d-7d56cd5d38a9:477",
   "typ": "Bearer",
   "azp": "db2ffeac6c0f402b87712530981e9871",
   "auth_time": 0,
   "session_state": "28b39feb-b921-44de-ac9e-4294de71c2cf",
   "acr": "1",
   "realm_access": {
     "roles": [
       "Aa", "Ac", "Ad", "Af", "Ag", "Ai", "Aj", "Al", "An", "Ao", "AA", "AB", "AD", "AE", "AG", "AH",
       "AJ", "AK", "AL", "AM", "AN", "AO", "AQ", "AR", "AT", "AU", "AV", "AW", "AX", "AY"
     ]
   },
   "scope": "mdpapp",
   "preferred_username": "393351234567",
   "druid_userid":477,
   "droppay_identity": "DPI19487191",
   "droppay_accounts": "IT86M3606400001393351234567,IT89M3606400001I05034550166"
   "apn": "DropPay Mobile App"
 }
Must be noticed that, for the goals of the TPP, the claim droppay_accounts is the most important one as long as it informs about the IBAN list of Accounts through which user can operate. IBAN value selected by user after authentication is needed to be passed in as argument to API method on order to perform the desired and available operation.

During the Resource Access phase TPP can consume DropPay API services.

The HTTP Authorization request header must be filled with the JWT access token already obtained during authentication phase.

During Resource Access phase the eIDAS certificate is not needed to establish the HTTPS connection. Identification and Authentication are accomplished through the valid previously issued JWT access token.

sequenceDiagram participant T as TPP participant S as DropPay T->>S: Request over HTTPS Note over T,S: Authorization: Bearer eyJhbGciOi...DsMCHs09og S-->>T: Response

For further informations about the RESTful API requests and responses, as long as possible errors returned, please proceed to (DropPay API Reference):