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 CIC Banque Privée, 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, CIC Banque Privée.
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 CIC Banque Privée, 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
andclient_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;
- set in a
- 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
andstate
in case of success;error
,error_description
andstate
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 HTTPPOST
on the confirmation endpoint/payment-requests/{paymentId}/confirmation
, with the returnednonce
in the request body;
Card-Based Payment Instrument Issuers (CBPII)
Support for CBPII by CIC Banque Privée 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.