PSD2 OAuth2

Overview

OAuth2 API enables a third-party application to obtain secured access to La Banque Postale's APIs.
Whether you are an AISP, a CBPII or a PISP, you will need to retrieve an access token to be able to request our endpoints.

Test it with the SandBox !

Functional details

This API relies on the OAUTH 2.0 Authorization Framework defined in RFC 6749.

Use Cases

Different authorization grants can be used, depending on the TPP's role and use case to be applied.

    • Get an access token to request AISP or CBPII APIs, following the OAuth 2.0 Authorization Code Grant procedure
    • Refreshing an access token to request AISP or CBPII APIs
    • Get an access token to request PISP API, following the OAuth 2.0 Client Credentials Grant procedure

La Banque Postale does not support refresh token procedure.
Implementation of changes to the RTS DSP2 concerning the minimum time between 2 strong authentications (RTS 12/2022) : Access tokens issued by La Banque Postale for AISP or CBPII scope have a 180 days lifetime. After 180 days, TPP must restart a new enrolment procedure with the customer's consent (PSU).

Redirect WEB - Specific error return codes at the end of the Redirect flow

During the TPP enrolment flow, various types of blockages may occur. In these contexts, the redirection to the TPP's redirect_uri is carried out with an error parameter detailing the problem encountered.

Here is the list of possible codes:

  • SCA_PSU_CANCELLATION : Cancellation of the Certicode Plus or Certicode OTP operation by the PSU
  • SCA_PSU_TIMEOUT : Timeout for Certicode Plus strong authentication validation
  • SCA_PSU_FAIL : Blocking of Certicode Plus service after 3 consecutive wrong MPIN entries
  • NUMBER_SCA_EXCEEDED : The number of SCAs authorised for the PSU over the day is exceeded
  • SCA_PSU_METHOD_ERROR : Customer has no strong authentication method or strong authentication method disabled
  • SCA_PSU_METHOD_ERROR_OTP_SUSPENDED : Blocking of the CERTICODE OTP service after 3 consecutive wrong entries of the OTP

Redirect App2App flow - Description and specific error return codes

As defined in RFC 8252, the implementation of the App to App redirect authentication journey allows for an automatic switch between the LBP App and the TPP App. The customer no longer needs to click on the notification or manually launch the bank's App. The customer no longer needs to manually relaunch the TPP App.

Caution: The App2App workflow requires the customer to use the device on which he has enrolled the CERTICODE PLUS.

The journey is thus optimized (fluid redirection) to avoid losing customers in interactions (necessary related to strong customer authentication) between the TPP and the bank.

The App2App route requires the use of a browser compatible with Universal Link (Chrome, Safari, Ecosia, etc.).

During the App2App flow, various types of blockages may occur. In these contexts, the redirection to the TPP's redirect_uri is carried out with an error parameter detailing the problem encountered.

Here is the list of possible codes:

  • SCA_PSU_CANCELLATION : Cancellation of the Certicode Plus or Certicode OTP operation by the PSU
  • SCA_PSU_TIMEOUT : Timeout for Certicode Plus strong authentication validation
  • SCA_PSU_METHOD_ERROR : Customer has no strong authentication method
  • SCA_PSU_DEVICE_ERROR : The operation is not possible because the device used is not the device enrolled by the customer
  • SCA_PSU_METHOD_ERROR_WAITING_FOR_VALIDATION : The operation is not possible because the customer's CERTICODE PLUS service is not active; it is waiting for validation
  • SCA_PSU_METHOD_ERROR_PENDING_ENROLLMENT : The operation is not possible because the CERTICODE PLUS service of the customer is not active; it is waiting for enrolment of a device
  • SCA_PSU_METHOD_ERROR_SUSPENDED_ENROLLMENT : The operation is not possible because the customer's CERTICODE PLUS service is blocked and waiting for a device to be enrolled
  • SCA_PSU_METHOD_ERROR_DISABLED : The operation is not possible because the customer's CERTICODE PLUS service is disabled
  • SCA_PSU_METHOD_ERROR_CANCELED : The operation is not possible because the CERTICODE PLUS service of the customer is terminated
  • SCA_PSU_METHOD_ERROR_SUSPENDED : The operation is not possible because the CERTICODE PLUS service of the customer is blocked
  • TPP_ENROLLMENT_TECHNICAL_ERROR : The operation is not possible due to a temporary technical error

Technical details

Endpoints: https://oauth2.labanquepostale.com

Redirect_uri parameter has to be URL-encoded and must correspond to the one stored during the APP Register process.
When you use an expired token, you get an 401 - unauthorized error, you must restart a new enrolment procedure with the customer's consent (PSU).

Prerequisites

Examples

    • Authorization code grant for AISP and CBPII

GET /authorize (redirect WEB) or GET /pph/authorize (App2App for individual customers) ou GET /pmo/authorize (App2App for professional customers)
Query string parameters:

response_type=code&client_id=abh007d2-345c-4asf-8196-fb4kiob2047b&redirect_uri=https%3A%2F%2FmyTPP-App.fr%2Fdsp2%2Fcallback&scope=aisp&state=data_for_TPP_use

    • Access token request for AISP and CBPII

POST /token or POST /pph/token (App2App for individual customers) or POST /pmo/token (App2App for professional customers)

The call to the POST /pph/token and POST /pmo/token APIs must be consistent with the GET /pph/authorize and GET /pmo/authorize API call.

Headers:

Content-Type: application/x-www-form-urlencoded
        Authorization: Basic YWFjNBH3ZDItMzC4Yy00ZGJmLTgxNzYtYks3X0QxZ3Y08xZkg5alI0c0ozaEs2bkY4eUIx

Body:

grant_type=authorization_code&scope=aisp&redirect_uri=https%3A%2F%2FmyTPP-App.fr%2Fdsp2%2Fcallback&code=AAJ542fS7FQieera-PouA1tuGbRG1VaGq_YIiIJF3bOIl9sidP0HEr2zpQpAsGho6ILV2w_-Q

    • Access token request for PISP

POST /token

Headers:

Content-Type: application/x-www-form-urlencoded
        Authorization: Basic YWFjNBH3ZDItMzC4Yy00ZGJmLTgxNzYtYks3X0QxZ3Y08xZkg5alI0c0ozaEs2bkY4eUIx

Body:

grant_type=client_credentials&scope=pisp