The Payment Services Directive 2015/2366 (PSD2) and the related RTSs have extensive requirements concerning the conditions under which financial data regarding a payment service user (PSU) can be shown.

We have chosen to implement these requirements by following the framework produced by the STET working group, available on its website.

The logic and implementation of these workflows heavily references the OAuth 2 framework workflows and vocabulary, specified in RFC 6749.

General Principles for Strong Customer Authentication

In order to proceed with Strong Customer Authentication, we universally rely on a redirect workflow, known as the OAuth 2 Authorization Code workflow:

• The Third Party Payment Service Provider (TPP) is given a URL of an OAuth 2 authorization endpoint hosted by the Account Servicing Payment Service Provider (ASPSP);
• The TPP fills URL query string parameters for the authorization endpoint, according to the specification;
• The TPP instructs the Payment Service User (PSU) to visit the parametrized URL. The TPP must ensure, to its satisfaction, the PSU's identity before giving him the URL - in particular, it should use the OAuth 2 state parameter to bind the PSU's browser context with a given transaction, to protect against attacks where a nefarious party transmits the filled redirection endpoint URL to a third party;
• The PSU performs the Strong Customer Authentication process on the ASPSP website:
  • The PSU is shown a page that asks them whether they agree to grant the TPP access to their data, or to allow an operation initiated by the TPP;
  • If the PSU agrees, they will be asked to authenticate strongly, in order to ensure the safety of the agreement process;
• Whether the PSU agrees or not, they will eventually be redirected to the TPP's redirection endpoint, using the standard OAuth 2 authorization response parameters;
  • In case the PSU has agreed, the TPP will be given an OAuth 2 authorization code, to be used with the OAuth 2 token endpoint described on the OAuth 2 endpoints page to get an access token;
  • In case of an error, or if the PSU did not agree, the TPP will be given an error code and a message describing the cause of the error. That message is a technical message, and should not be shown to the PSU on the TPP UI.

In order to obtain an OAuth 2 Client ID, the TPP must complete the registration process.

Account Information Service Providers (AISP)

Getting access to the PSU's data

In order for Account Information Service Providers to access a PSU's banking data at Monabanq, the user must agree to authorize access to their data by the Third Party Account Information Service Provider, and that agreement must be registered by the ASPSP, Monabanq.

That authorization process takes the form of an OAuth 2 Authorization Code workflow, with the following implementation specificities:

• The OAuth 2 authorization endpoints are listed on the OAuth 2 Endpoints page;
• The use of the OAuth 2 PKCE extension is mandatory, with the SHA-256 method;

Once that process is completed successfully, the TPP will be given an authorization code, which they will be able to use to obtain both an initial access token and a refresh token.

Getting new access tokens without an SCA

In order for the TPP to get new access tokens without requiring the PSU to go through an SCA process, the TPP can use the refresh token provided at the end of the authorization code workflow to obtain a new access token.

Access tokens obtained in this way only provide access to information for which an SCA is not necessary.

Scopes

The following scopes are supported for AISPs:

• aisp
• aisp extended_transaction_history

The first scope gives access to the PSU's recent transaction history and account information, while the second scope is necessary to get a transaction history beyond the last 90 days.

It should be noted that:

• Both scopes can be used for Authorization Requests;
• Both scopes can be set on Access Tokens issued from an OAuth 2 authorization code;
• Only the first scope can be set on Access Tokens issued from an OAuth 2 refresh token;

SCA Expiration and renewal

Following the PSD2 RTS and clarifications published by the EBA, AISP access granted by the PSU stays valid for a duration of 180 days. This access is materialized by a refresh token that stays valid for that whole duration.

When the 180 days period is elapsed, the refresh token will automatically expire and requests to get new access tokens from it will return an invalid_grant error.

In that case, the TPP must ask the PSU to renew their grant of access, by instructing the PSU to visit the OAuth 2 authorization endpoint.

Payment Initiation Service Providers (PISP)

Getting an access token for Payment Initiation

In order to use the API endpoints for payment initiation, an OAuth 2 access token must be presented to the API. That token is obtained by making a Client Credentials Access Token Request on the OAuth 2 Token Endpoint.

The only valid value for the scope parameter in that request is pisp. Setting it in the request body is optional.

Payment Initiation Workflows

In payment initiation workflows, a redirection workflow is used in all cases, that is, the TPP is provided with a URL of a web page controlled by Monabanq, on which the PSU should be sent to confirm the initiated payment's execution, after which the PSU's user agent is redirected to the TPP's callback URL.

Depending on the API versions, the payment initiation workflow differs:

• For API versions 2.x, the redirection workflow is an OAuth 2 workflow, in conformance with STET PSD2 API Specification version 1.4.2;
• For older API versions (1.0/1.1), the redirection workflow is not an OAuth 2 workflow;

OAuth 2 Payment Initiation Workflow (API v2.x)

The target payment initiation workflow is an OAuth 2 Authorization Code workflow, with the following implementation specifics:

• The Authorization Endpoint URL is returned in the response to a Payment Initiation Request on the API, in the $._links.consentApproval of the returned JSON object;
• As a courtesy, in that Authorization URL, the parameter values for OAuth 2 parameters response_type, scope and client_id are set - a change in the value of one of these parameters will result in an error;
• The redirection URL must be:
  • set in a redirect_uri query parameter to the authorization endpoint, as is standard for OAuth 2;
  • Registered with the associated client_id on the OAuth 2 Client Registration API;
• The use of the OAuth 2 PKCE extension is mandatory, with the SHA-256 method;
• The TPP callback is called with the OAuth 2 authorization response parameters:
  • code and state in case of success;
  • error, error_description and state in case of error;

TPPs that are used to the legacy workflow should note that, in the OAuth 2 workflow, the successfulReportUrl and unsuccessfulReportUrl fields are not used for the determination of the redirection URL.

Once the PSU has confirmed the payment execution (and the corresponding authorization code has been obtained by the TPP), a HTTP POST to the OAuth confirmation endpoint /payment-requests/{paymentId}/o-confirmation, using an access token derived from the authorization code, must be done in order for payment execution to occur.

Payment Request Cancellation Workflows

In order to cancel a payment, a HTTP PUT request on the initiated payment's URL must be made.

If the cancellation request is valid, the workflow for confirming cancellation depends on the API version:

• For API versions 2.x, a nonce will be returned, and the cancellation will be effective once a HTTP POST on the confirmation endpoint /payment-requests/{paymentId}/confirmation, with the returned nonce in the request body;

Card-Based Payment Instrument Issuers (CBPII)

Support for CBPII by Monabanq uses exactly the same workflows as the AISP case, with the following modifications:

• The scope for CBPII is cbpii - this scope can be set on Access Tokens issued from an OAuth 2 authorization code, or from an OAuth 2 refresh token;

A CBPII cannot use an OAuth 2 Client Credentials workflow to obtain an OAuth 2 access token.