Overview
The expected benefits
Simplify your access to the PSD2 services of the banking institutions of the Groupe BPCE.
The PSD2 Registration API provides Third Party Providers (TPPs) with access to our innovative solution to optimize the management of their clients' financial transactions. Thanks to its automation, it reduces errors, improves the speed of operations and enhances data security. By integrating this API, companies benefit from simplified compliance and an improved user experience, thereby fostering customer loyalty.
Automation of registrations
Simplifies the registration process for consumer applications, reducing manual errors.
Acceleration of financial services
Improves the speed of transactions for a smooth and immediate user experience.
Improvement of security
Enhances data security through advanced protection protocols.
Facilitation of integration
Allows easy integration with existing systems, minimizing operational disruptions.
The service offering of the PSD2 Registration API is based on the automation of registration processes for consumer applications, guaranteeing regulatory compliance and data security while facilitating access to banking services.
The different possible use cases
This API product is essential for using the PSD2 solutions provided by Groupe BPCE.
Initial registration of a consumer application.
- This step must be carried out by any new TPP who wishes to access and consume the resources of the exposed PSD2 APIs.
- Any TPP already using our PSD2 APIs can also use this API to be independent in updating the information of their project and their consumer app. In this case, they must use this API.
- The TPP can also declare several consumer applications, and therefore agents of these TPPs who can also be declared via this intermediary.
Data retrieval
This API product allows you to retrieve data regarding the technical registration.
Data Modification
It also allows you to modify the data provided regarding the registration of a consumer application, including, for example, eIDAS certificates that are expiring.
Deletion of registration
Possibility to delete the global registration of a consumer application, which is necessary, for example, in the event of obsolescence of the latter.
How to access the product ?
To access the PSD2 Registration API, developers and businesses must follow the steps below.
Check eligibility
The resources of this API can only be consumed if you have obtained the status of Payment Service Provider (PSP). For more information, please refer to the 'Eligibility' section.
Test with the sandbox
Before you get started, test the API product in your environment.
Get started !
Are you ready ? Then get started with live production.
Documentation
Guides
Main API methods
The main uses cases leading to API methods are described below :
First TPP app enrolment
This step is necessary for all new TPP willing to access for the first time to our PSD2 API.
All TPP having already used our PSD2 API can also use this API REGISTER in order to be self autonomous for updating their new apps.
The TPP agents can also be registered using this API with a different name from TPP’s one (one request per agent).- Extract data of an already existing registered app
- Modify a registered app data e.g. if eIDAS certificats are about to expire
- Remove all registered app data e.g. if the app is obsolete (full deletion)
Get the access token
Prerequisites
In order to be able to use this API, all PSD2 TPP need to have a national EU agreement delivered by a NCA, as well as a Unique Reference Number of Organization Identifier (OID).
For any further information, ETSI international standard specifies this OID as described in « Eligibility » section.
This OID is also included in eIDAS certificates (QWAC & QSealC) used for PSD2 API access and mutual authentication process (between TPP and ASPSP).
How to use this API ?
The POST /token method of this API is mandatory in first row and allows TPP to get a new client_id which will be used for the other API REGISTER methods.
The following entry points for the POST /token are as follows :
- Sandbox : https://www.<codetab>.sandbox.api.89C3.com/stet/psd2/oauth/token
The generic client_id to be used to get the access token is “PSD2_TPPRegister“
- Production Live : https://www.<codetab>.live.api.89C3.com/stet/psd2/oauth/token
The generic client_id to be used to get the access token is “PSD2_TPPRegister“
Please note that any valid value of one of ASPSP available on this BPCE API Portal can be used. Even if one ASPSP is used, the registration applies to all ASPSP.
Example (sandbox)
POST https://www.17515.sandbox.api.89C3.com/stet/psd2/oauth/token
Header : Content-type : application/x-www-form-urlencoded; charset=utf-8
Params :
client_id : 9d8711ec-f1b4-45e4-8072-2b3aa49793f0
grant_type : client_credentials
scope : manageRegistration
<!-- Note : TPP needs to use a TLS mutual authentication based on QWAC certificate with this
POST /token method. --> Response :
{
“access_token” : “KXyZabcdefghijklmopqrstuvw1234567890”
}
Once this temporary access token is received, the following API methods are available:
| Method | Path | Description / Use-case |
|---|---|---|
| POST | /register | Method to register an app or an agent |
| PUT | /register/${client_id} | Method to change an app data |
| GET | /register/${client_id} | Method to extract app data |
| DELETE | /register/${client_id} | Method to remove an app |
Self enroll an app or an agent
Prerequisites
In order to be able to use this method, you need to fulfill the eligibility criteria.
POST /register
Example (sandbox) : POST https://www.17515.sandbox.api.89C3.com/stet/setting/v1/register
Please check the documentation tab.
HTTP Headers
| Name | (O)ptional (R)equired | Description |
|---|---|---|
| x-request-id | R | Request correlation id. This id must be a string generated by the TPP. |
| signature | R | One of the main information of this registration is the TPP QSEALC certificate which will used by BPCE to verify the signature of all the DSP2 streams. As TPP identification is not yet known at the time of this initial request, TPP has to provide the certificate in the body itself, in the first item of the keys table. The certificate information will be retrieved from this form and will be used to verify the signature of the initial request and all future DSP2 requests. Please note that a TPP agent cannot use directly this API set, reserved for the TPP acting on behalf of an agent (only the TPP certificate is authenticated). In case of agents, flows must also be signed with a TPP QSEALC valid certificate. |
| digest | R | SHA256 body digest base64 encoded. |
| authorization | R | Bearer access_token previously received. |
HTTP Body
| Name | (O)ptional (R)equired (F)orbidden | Description |
|---|---|---|
| redirect_uris | R | String array. It contains all URIs (scheme and authority according to RFC 3986, comma separated) that TPP can use in DSP2 redirect requests. Any URI used afterwards in PSD2 API but not provided in this registration process will be refused. |
| software_statement | O | String. JSON Web Token (JWT). Not used. |
| token_endpoint_auth_method | R | String. Value shall be “tls_client_auth”. |
| grant_types | R | String array. Value shall be “client_credentials”. |
| response_types | R | String array. Value shall be “code”. |
| client_name | R | String. This is the TPP unique legal name. |
| client_uri | O | String. TPP or agent Web page URI. Not used. |
| logo_uri | O | String. TPP or agent logo URI. Not used. |
| scope | R | String. TPP scopes are comma separated, and possible values are : “aisp” and/or “pisp” and/or “cbpii” Example : “aisp” Example : “aisp, pisp” Note : the scope is also mandatory for agents. In that case, the values included in this field shall be the ones from the TPP. |
| contact | R | String. Data for mandatory contact details : “contact”: { “contact_name”: “string”, “email”: “string”, “phone_number”: “string” } |
| tos_uri | O | String. Data for mandatory contact details : “contact”: { “contact_name”: “string”, “email”: “string”, “phone_number”: “string” } |
| policy_uri | O | String. URI that points to a human-readable policy document for the client. Not used. |
| jwks_uri | O | String. URL referencing the client JSON Web Key (JWK) document containing the client public keys. Not used. |
| provider_legal_id | R | String. TPP National Authorization number according to ETSI specification on eIDAS certificates for PSD2 (OID = PSDXX-YYYYYYYY-ZZZZZZZZ, see “Eligibility” section). |
| client_legal_id | R/O(*) | String. (*) Optional for a TPP / Mandatory (required) for an agent. This identifier is therefore left to the discretion of the TPP for an agent. However, its format should comply with the ETSI specification on DSP2 eiDAS certificates with “AGT” suffix + a serial number, e.g. “AGTFR-ACPR-12345001”. Note : in order to avoid rejection due to a duplicated alues, we strongly advise to base it on truncated OID TPP number (= no PSD prefix) before the serial number. |
| logo | O | String. Not used. |
| jwks | R | Object. This object contains the following array and shall contain at least one public key (QSEALC) without the chain link to the certification authority. |
| keys | R | JWK objects array. This array shall contain only one item (JWK). |
| kty | R | String. Key type. Value shall be “RSA”. |
| use | R | String. Key usage. Vallue shall be “sig”. |
| alg | R | String. Value shall be “RS256”. |
| key_ops | R | String array. Value shall be “verify”. |
| kid | R | String. Key id. |
| x5u | F | Not used. |
| x5c | R | String array. Must not contain more than one item representing the QSEALC certificate in DER format based on 64. |
| x5t | F | Not used. |
| x5t#S256 | R | String. SHA256 fingerprint of X509 DER certificate. |
| software_id | R | String. Mandatory name of the TPP app OR brand name OR agent name which will be displayed to PSU (it can be different from the client_name). This parameter is dispayed in priority to PSU during SCA redirect process. |
| software_version | R | String. Mandatory name of the TPP app OR brand name OR agent name which will be displayed to PSU (it can be different from the client_name). This parameter is dispayed in priority to PSU during SCA redirect process. |
Response
A correct response returns a HTTP 201 status.
The TPP will also receive its client_id to be used in all PSD2 methods, including methods 2 to 4 of this document
Errors
| HTTP STATUS | DESCRIPTION |
|---|---|
| 400 | Bad request. Error is supplied in fields error and error_description. |
| 404 | Resource not allowed. |
| 405 | Method not allowed. A method other than those described here was used. |
| 500 | Internal server error. |
Change an app data
Prerequisites
In order to be able to use this method, you need to fulfill the eligibility criteria.
To modify at least one app data; the “client_id” is the one received using the method POST /register.
PUT /register/{client_id}
Example (sandbox) : PUT https://www.17515.sandbox.api.89C3.com/stet/setting/v1/register/AGTFR-ACPR-12345001
with the client_id = the one the TPP received in our response of the enrolment (using the POST /register).
Please check the documentation tab.
HTTP Headers
| NAME | (O)PTIONNAL / (R)EQUIRED | DESCRIPTION |
|---|---|---|
| x-request-id | R | Request correlation id. This id must be a string generated by the TPP. |
| signature | R | As registration requests must also provide a signature, the TPP must sign this request with the private key corresponding to the QSEALC certificate. |
| digest | R | SHA256 body digest base 64 encoded. |
| authorization | R | bearer access_token previously received. |
HTTP Body
| NAME | (O)PTIONNAL / (R)EQUIRED / (F)ORBIDDEN | DESCRIPTION |
|---|---|---|
| redirect_uris | R | String array. It contains all URIs (scheme and authority according to RFC 3986, comma separated) that TPP can use in DSP2 redirect requests. Any URI used afterwards in PSD2 API but not provided in this registration process will be refused. |
| token_endpoint_auth_method | R | String. Value shall be “tls_client_auth”. |
| grant_types | R | String array. Value shall be “client_credentials”. |
| response_types | R | String array. Value shall be “code”. |
| client_name | R | String. This is the TPP unique legal name. |
| client_uri | O | String. TPP or agent Web page URI. Not used. |
| logo_uri | O | String. TPP or agent logo URI. Not used. |
| scope | R | String. TPP scopes are comma separated, and possible values are : “aisp” and/or “pisp” and/or “cbpii” Example : “aisp” Example : “aisp, pisp” Note : the scope is also mandatory for agents. In that case, the values included in this field shall be the ones from the TPP. |
| contact | R | String. Data for mandatory contact details : “contact”: { “contact_name”: “string”, “email”: “string”, “phone_number”: “string” } |
| tos_uri | O | String. URI that points to a human-readable terms of service document for the client. Not used. |
| policy_uri | O | String. URI that points to a human-readable policy document for the client. Not used. |
| provider_legal_id | R | String. TPP National Authorization number according to ETSI specification on eIDAS certificates for PSD2 (OID = PSDXX-YYYYYYYY-ZZZZZZZZ, see “Eligibility” section). |
| client_legal_id | R/O(*) | String. For a TPP / Mandatory (required) for an agent. This identifier is therefore left to the discretion of the TPP for an agent. However, its format should comply with the ETSI specification on DSP2 eiDAS certificates with “AGT” suffix + a serial number, e.g. “AGTFR-ACPR-12345001”. Note : in order to avoid rejection due to a duplicated alues, we strongly advise to base it on OID TPP number before the serial number. |
| logo | O | String. Not used. |
| jwks | R | Object. This object contains the following array and shall contain at least one he public key (QSEALC) without the chain link to the cartification authority. |
| keys | R | JWK objects array. This array should only contain one item (JWK). |
| kty | R | String. Key type. Value shall be “RSA”. |
| use | R | String. Key usage. Vallue shall be “sig”. |
| alg | R | String. Value shall be “RS256”. |
| key_ops | R | String array. Value shall be “verify”. |
| kid | R | String. key id. |
| x5u | F | Not used. |
| x5c | R | String array. Must not contain more than one item representing the QSEALC certificate in DER format based on 64. |
| x5t | F | Not used. |
| x5t#S256 | R | String. SHA256 fingerprint of X509 DER certificate. |
| software_id | R | String. Mandatory name of the TPP app OR brand name OR agent name which will be displayed to PSU (it can be different from the client_name). This parameter is dispayed in priority to PSU during SCA redirect process. |
| software_version | O | String. Not used. |
Response
A correct response returns a HTTP 201 status.
Errors
| HTTP STATUS | DESCRIPTION |
|---|---|
| 400 | Bad request. Error is supplied in fields error and error_description. |
| 404 | Resource not found. |
| 405 | Method not allowed. A method other than those described here was used. |
| 500 | Internal server error. |
Extract app data
Prerequisites
In order to be able to use this method, you need to fulfill the eligibility criteria.
To modify at least one app data; the “client_id” is the one received using the method POST /register.
GET /register/{client_id}
Example (sandbox) : GET https://www.17515.sandbox.api.89C3.com/stet/setting/v1/register/AGTFR-ACPR-12345001
with the client_id = the one the TPP received in our response of the enrolment (using the POST /register).
Please see the documentation tab.
HTTP Headers
| NAME | (O)PTIONNAL / (R)EQUIRED | DESCRIPTION |
|---|---|---|
| x-request-id | R | Request correlation id. This id must be a string generated by the TPP. |
| Signature | R | As registration requests must also provide a signature, the TPP must sign this request with the private key corresponding to the QSEALC certificate. |
| Authorization | R | bearer access_token previously received. |
Response
A correct response returns a HTTP 200 status.
Errors
| HTTP STATUS | DESCRIPTION |
|---|---|
| 400 | Bad request. Error is supplied in fields error and error_description. |
| 404 | Resource not found. |
| 405 | Method not allowed. A method other than those described here was used. |
| 500 | Internal server error. |
Remove app data
Prerequisites
In order to be able to use this method, you need to fulfill the eligibility criteria.
To modify at least one app data; the “client_id” is the one received using the method POST /register.
DELETE /register/{client_id}
Example (sandbox) : DELETE https://www.17515.sandbox.api.89C3.com/stet/setting/v1/register/AGTFR-ACPR-12345001
with the client_id = the one the TPP received in our response of the enrolment (using the POST /register).
Please see the documentation tab.
HTTP Headers
| NAME | (O)PTIONNAL / (R)EQUIRED | DESCRIPTION |
|---|---|---|
| x-request-id | R | Request correlation id. This id must be a string generated by the TPP. |
| Signature | R | The TPP must sign this request with the private key corresponding to the QSEALC certificate. |
| Authorization | R | bearer access_token previously received. |
Response
A correct response returns a HTTP 204 status.
Errors
| HTTP STATUS | DESCRIPTION |
|---|---|
| 400 | Bad request. Error is supplied in fields error and error_description. |
| 404 | Resource not found. |
| 405 | Method not allowed. A method other than those described here was used. |
| 500 | Internal server error. |
API deprecation process
According to API product life cycle, an API version can be deprecated (meaning this API is not any more accessible on gateways and sandbox).
An overlap period between two major API releases is provided as described below :
The communication around the decommissioning process of a version N will be done at the release date of version N+1 through this portal / “roadmap” section.
Roadmap
This API is subject to continual reviews and improvements throughout the year.
Limits
This API can’t be used to modify an already existing app which has been enroled using the BPCE dev portal. In this case, TPP has to perform the full process using this API, and will receive a new client_id.
Please note that if a TPP requires a new profile (= new cliend_ID), it has to use another set of eIDAS certifciates.
An agent which doesn’t have its own OID and eIDAS certificates can’t use this API. The TPP (linked to the agent) will have to use this API based on his own OID and eIDAS certificates in order to declare the app of its agent.
If the API is correctly used and returns http 20x code, the newly generated client_id (or data modifications) will be automatically taken into account the next working day @02:00 pm continental time (or on the very same day if the 09:59 am deadline is not reached) except if at least one elligibility criteria doesn’t apply (it could generate additional delays – see next section).
Please also note that:
- eIDAS certificates signed with “rsassaPss” cryptographic algorihtm are not accepted ;
- the access token validity is limited to 1 hour.
Eligibility
The API resources can only be used by Payment Service Providers (PSP) having a Account Information Service Providers (AISP) role.
In order to provide a service to users of payment informations services under PSD2 directive, you must be a licenced PSP such as credit institution, electronic money institution, and payment institution. This status is delivered by the national authorities of the country where the request is made. In France, it is the “Autorité de Contrôle Prudentiel et de Résolution (ACPR), under the supervision of the Banque de France regulatory body, see https://acpr.banque-france.fr/sites/default/files/medias/documents/jch_20180403_conference_securite_des_paiements.pdf.
Obtaining and maintaining such agreement requires rigorous procedures in order to give strong guarantees to the account informations services users. The forms are provided on the ACPR website : https://acpr.banque-france.fr/en/authorisation/banking-industry-procedures/all-forms.
Once the agrement is granted, the Organisation Identifier (OID) given by the national authority has the following format (UPPER case): PSDXX-YYYYYYYY-ZZZZZZZZ
- “PSD” as 3 character legal person identity type reference
- 2 character ISO 3166 country code representing the NCA country
- hyphen-minus “-” (0x2D (ASCII), U+002D (UTF-8)) and
- 2-8 character NCA identifier (A-Z uppercase only, no separator)
- hyphen-minus “-” (0x2D (ASCII), U+002D (UTF-8)) and PSP identifier (authorization number as specified by NCA)
This OID is very important to identify yourself as a TPP :
- using STET API requests as OID is included in the parameter “client_ID”
- using mutual authentication (TLS) as OID is included in eIDAS certificates to be delivered to the bank (see below)
You also need eIDAS (electronic IDentification And trust Services) compliant certificates delivered by a valid Qualified Certification Service Provider (QTSP, see list available on https://webgate.ec.europa.eu/tl-browser/#/).
In order to be able to consume PSD2 API published on our BPCE Portal, you have to use eIDAS valide certificates signed by a QTSP with production “live” keys :
- a set of QWAC and et QSEALC of certificates for the sandbox environment
- another set of QWAC and et QSEALC certificates for the live production environment
In case of access problems due to certificates, we will check if your QWAC certificates are signed with a new Certification Authority (CA) or with a new root (from an existing CA). In both cases, an additional delay is expected (est’d 2 weeks) for loading it on our infrastructure.
Please embed only public keys in .pem format. Controls on data included in the certificates will be based on European Banking Association TPP register https://euclid.eba.europa.eu/register/pir/disclaimer).
You can also refer to the FAQ section.
History
STET Compliance
This REST-based API is compliant with the STET specifications developed by the French market initiative (https://www.stet.eu/en/psd2/) in order to comply with PSD2 regulatory requirements. It takes into account functional limitations specific to this retail bank network (see use case "Limitations").
As a reminder :
- payment services directive (PSD2, (UE) 2015/2366 of 25/11/2015) went into force on january 13, 2018 : https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=celex%3A32015L2366
- it is supplemented by regulatory technical standards for strong customer authentication (RTS, Commission Delegated Regulation (EU) No 2018/389) and common and secure open standards of communication that will apply on september14, 2019. These standards are called RTS (Rules Technical Standards): https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32018R0389
In France, the ordinance n° 2017-1252 of August 9, 2017 implements the PSD2 directive into the regulatory section of the monetary and financial code. This ordinance has been supplemented by two decrees (n° 2017-1313 and n° 2017-1314), and five orders that were published on August 31, 2017.
You can also refer to the FAQ section.
Description of TPP support
According to Article 30 (5) of the RTS, a support for third-party providers is available. This support can be joined via the form on this Groupe BPCE API Store. Responses are sent during office opening hours Central European local Time even so a 24h/7d monitoring process of our IT systems exists).
Its general principle is shown below, taking into account delays of Article 30 (4) of the RTS :
Important changes
Important changes made since the first version of this documentation was published :
| USE CASE / METHOD(S) | EFFECTIVE DATA | DESCRIPTION OF THE EVOLUTION |
|---|---|---|
| All | March 17, 2021 | Editorial Changes |