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

    {}

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

• 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

{
  "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;

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

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 <br> username=393331234567 <br>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:

{
  "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:

{
  "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).

Resource Access¶

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):

• PISP - Payment - DropPay API Payment Initiation
• AISP - Account informations DropPay API Account Info