API Register
Réalisez vous-même votre enrôlement sur les API DSP2 du groupe BPCE
-
Vue d'ensemble
Fonctionnalités principales
Le Groupe BPCE met à disposition des prestataires de services de paiements DSP2 (TPP) une API leur permettant de s’enregistrer (ou de modifier l’enregistrement), basée sur :
- les spécifications STET version V1.4.2 / paragraphe 3.4.2.1
et
- le swagger « DSP2 Oauth2 Technical » setup / swagger TechnicalSetup_1.0.5_OAS2.yaml. Ce dernier est basé sur les RFC 7591, 7592 et 7517, et est complété par cette fiche
Cette API est réservée pour :
- les TPP DSP2 n’ayant jamais enregistré d’applications consommatrices
ou
- les TPP DSP2 ayant déjà enregistré une/des applications consommatrices via cette API et souhaitant modifier une donnée (par exemple, des certificats eIDAS qui arrivent à expiration).
Catégories
-
Vue d'ensemble
/stet/setting/v1/register/{clientId}
registrationDelete
RÉSUMÉ
Delete the actual registration for a given client_id
DESCRIPTION
[From RFC7592] To deprovision itself on the authorization server, the client makes an HTTP DELETE request to the client configuration endpoint. This request is authenticated by the registration access token issued to the client.
SCOPES
- manageRegistration
PARAMÈTRES
| clientId (required) |
string
path
REQUIRED. OAuth 2.0 client identifier string. It SHOULD NOT be currently valid for any other registered client, though an authorization server MAY issue the same client identifier to multiple instances of a registered client at its discretion.
|
| Signature (required) |
string
header
http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is – either an URL aiming to provide the relevant Qualified Certificate. – or the kid parameter retrieved through the certificate registration during a previous OAUTH2 Technical Setup
|
| X-Request-ID (required) |
string
header
Correlation header to be set in a request and retrieved in the relevant response
|
CODES RETOUR
| 204 | No content. Deletion of the relevant registration |
| 400 | Invalid status value |
| 401 | Unauthorized, authentication failure. |
| 403 | Forbidden, authentication successful but access to resource is not allowed. |
| 405 | Method Not Allowed. |
| 406 | Not Acceptable. |
| 408 | Request Timeout. |
| 429 | Too many requests. |
| 500 | Internal server error. |
| 501 | Not Implemented. This code should be used when the entry point is implemented but cannot provide a result, given the context. When the entry point is not implemented at all, HTTP400 will be returned. |
| 503 | Service unavailable. |
AUTHENTIFICATIONS DISPONIBLES
OAuth 2.0
/stet/setting/v1/register/{clientId}
registrationGet
RÉSUMÉ
Retrieve the actual registration for a given client_id
DESCRIPTION
[From RFC7592] To read the current configuration of the client on the authorization server, the client makes an HTTP GET request to the client configuration endpoint, authenticating with its registration access token.
SCOPES
- manageRegistration
PARAMÈTRES
| clientId (required) |
string
path
REQUIRED. OAuth 2.0 client identifier string. It SHOULD NOT be currently valid for any other registered client, though an authorization server MAY issue the same client identifier to multiple instances of a registered client at its discretion.
|
| Signature (required) |
string
header
http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is – either an URL aiming to provide the relevant Qualified Certificate. – or the kid parameter retrieved through the certificate registration during a previous OAUTH2 Technical Setup
|
| X-Request-ID (required) |
string
header
Correlation header to be set in a request and retrieved in the relevant response
|
CODES RETOUR
| 200 | Retrieval of the registration |
| 400 | Invalid status value |
| 401 | Unauthorized, authentication failure. |
| 403 | Forbidden, authentication successful but access to resource is not allowed. |
| 405 | Method Not Allowed. |
| 406 | Not Acceptable. |
| 408 | Request Timeout. |
| 429 | Too many requests. |
| 500 | Internal server error. |
| 501 | Not Implemented. This code should be used when the entry point is implemented but cannot provide a result, given the context. When the entry point is not implemented at all, HTTP400 will be returned. |
| 503 | Service unavailable. |
AUTHENTIFICATIONS DISPONIBLES
OAuth 2.0
/stet/setting/v1/register
registrationPost
RÉSUMÉ
Client Registration request
DESCRIPTION
[From RFC7591] This operation registers a client with the authorization server. Theauthorization server assigns this client a unique client identifier, optionally assigns a client secret, and associates the metadata provided in the request with the issued client identifier. The request includes any client metadata parameters being specified for the client during the registration. The authorization server MAY provision default values for any items omitted in the client metadata. To register, the client or developer sends an HTTP POST to the client registration endpoint with a content type of « application/json ». The HTTP Entity Payload is a JSON [RFC7159] document consisting of a JSON object and all requested client metadata values as top-level members of that JSON object.
SCOPES
- manageRegistration
PARAMÈTRES
| access (required) |
RegistrationRequest
body Registration data submitted by a given client.
|
| Digest (required) |
string
header
Digest of the body
|
| Signature (required) |
string
header
http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is – either an URL aiming to provide the relevant Qualified Certificate. – or the kid parameter retrieved through the certificate registration during a previous OAUTH2 Technical Setup
|
| X-Request-ID (required) |
string
header
Correlation header to be set in a request and retrieved in the relevant response
|
CODES RETOUR
| 201 | Created |
| 400 | Invalid status value |
| 401 | Unauthorized, authentication failure. |
| 403 | Forbidden, authentication successful but access to resource is not allowed. |
| 405 | Method Not Allowed. |
| 406 | Not Acceptable. |
| 408 | Request Timeout. |
| 429 | Too many requests. |
| 500 | Internal server error. |
| 501 | Not Implemented. This code should be used when the entry point is implemented but cannot provide a result, given the context. When the entry point is not implemented at all, HTTP400 will be returned. |
| 403 | Service unavailable. |
ENTRÉES
application/json
AUTHENTIFICATIONS DISPONIBLES
OAuth 2.0
/stet/setting/v1/register/{clientId}
registrationPut
RÉSUMÉ
Update the actual registration for a given client_id
DESCRIPTION
[From RFC7592] To update a previously registered client’s registration with an authorization server, the client makes an HTTP PUT request to the client configuration endpoint with a content type of « application/json ». The HTTP entity payload is a JSON [RFC7159] document consisting of a JSON object and all parameters as top-level members of that JSON object. This request is authenticated by the registration access token issued to the client. This request MUST include all client metadata fields as returned to the client from a previous registration, read, or update operation. The updated client metadata fields request MUST NOT include the « registration_access_token », « registration_client_uri », « client_secret_expires_at », or « client_id_issued_at » fields described in Section 3. Valid values of client metadata fields in this request MUST replace, not augment, the values previously associated with this client. Omitted fields MUST be treated as null or empty values by the server, indicating the client’s request to delete them from the client’s registration. The authorization server MAY ignore any null or empty value in the request just as any other value. The client MUST include its « client_id » field in the request, and it MUST be the same as its currently issued client identifier. If the client includes the « client_secret » field in the request, the value of this field MUST match the currently issued client secret for that client. The client MUST NOT be allowed to overwrite its existing client secret with its own chosen value. For all metadata fields, the authorization server MAY replace any invalid values with suitable default values, and it MUST return any such fields to the client in the response.
SCOPES
- manageRegistration
PARAMÈTRES
| clientId (required) |
string
path
REQUIRED. OAuth 2.0 client identifier string. It SHOULD NOT be currently valid for any other registered client, though an authorization server MAY issue the same client identifier to multiple instances of a registered client at its discretion.
|
| access (required) |
RegistrationRecord
body
Registration data updated by a given client.
|
| Digest (required) |
string
header
Digest of the body
|
| Signature (required) |
string
header
http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is – either an URL aiming to provide the relevant Qualified Certificate. – or the kid parameter retrieved through the certificate registration during a previous OAUTH2 Technical Setup
|
| X-Request-ID (required) |
string
header
Correlation header to be set in a request and retrieved in the relevant response
|
CODES RETOUR
| 200 | Retrieval of the updated registration |
| 400 | Invalid status value |
| 401 | Unauthorized, authentication failure. |
| 403 | Forbidden, authentication successful but access to resource is not allowed. |
| 405 | Method Not Allowed. |
| 406 | Not Acceptable. |
| 408 | Request Timeout. |
| 429 | Too many requests. |
| 500 | Internal server error. |
| 501 | Not Implemented. This code should be used when the entry point is implemented but cannot provide a result, given the context. When the entry point is not implemented at all, HTTP400 will be returned. |
| 503 | Service unavailable. |
ENTRÉES
application/json
AUTHENTIFICATIONS DISPONIBLES
OAuth 2.0
Catégories
Méthodes Principales
Cette API permet d’effectuer les actions suivantes par le prestataire de paiements externe DSP2 (TPP) :
- 1er cas d’usage : enregistrement initial d’une application consommatrice
NB 1 : cette étape est à mener par tout nouveau TPP qui souhaite accéder et consommer les ressources des API DPS2 exposées
NB 2 : tout TPP utilisant déjà nos API DPS2 peuvent aussi utiliser cette API pour être indépendant sur la mise à jour des informations de son projet et de son app consommatrice. Dans ce cas, il doit utiliser cette API
NB 3 : le TPP peut aussi déclarer plusieurs applications consommatrices, et donc des agents de ces TPP qui pourront aussi être déclarés via cet intermédiaire
- 2ème cas d’usage : récupérer les données concernant l’enregistrement technique du TPP
- 3ème cas d’usage : modifier les données fournies concernant l’enregistrement d’une application consommatrice, dont par exemple, des certificats eIDAS qui arrivent à expiration
- 4ème cas d’usage : supprimer l’enregistrement global d’une application consommatrice, ce qui est nécessaire par exemple, en cas d’obsolescence d’une application consommatrice
Récupérer le jeton d'accès
Prérequis
Pour accéder à l’API Register, les TPP doivent :
- Etre agréés par leur Autorité Compétente Nationale, et le cas échéant, avoir un passporting en France pour les activités qu’ils souhaitent exercer en France
- Posséder un numéro de référence unique (Unique Reference Number ou Organisation Identifier : OID) obtenu par le TPP auprès de son Autorité Compétente Nationale (NCA) et qui permet d’identifier le TPP.
Plus généralement, la norme ETSI intègre ce numéro de référence dans une structure telle que décrite dans la rubrique « Eligibilité ».
Cette codification se retrouve dans les certificats eIDAS (QWAC et QSEALC) que les TPP doivent se procurer auprès d’une autorité de certification agréée pour pouvoir utiliser les API DSP2.
Comment utiliser l’API ?
La méthode POST /token est obligatoire et permet en premier lieu de générer un nouvel client_id qui sera nécessaire pour accéder aux autres méthodes de l’API REGISTER.
Pour la demande de jeton d’accès via POST /token, les points d’entrée sont les suivants :
Le client_id générique à utiliser pour récupérer un token d’accès pour utiliser l’API /register est « 9d8711ec-f1b4-45e4-8072-2b3aa49793f0″
- Production Live : https://www.<codetab>.live.api.89C3.com/stet/psd2/oauth/token
Le client_id générique à utiliser pour récupérer un token d’accès pour utiliser l’API /register est « PSD2_TPPRegister«
NB : N’importe quel <codetab> d’un ASPSP exposé sur ce portail peut être utilisé. Même si un seul <codetab> est utilisé, ce processus de déclaration d’un app consommatrice s’appliquera à tous les ASPSP.
Exemple (sandbox)
POST https://www.17515.sandbox.api.89C3.com/stet/psd2/oauth/token
Header : Content-type : application/x-www-form-urlencoded; charset=utf-8
Paramètres :
- client_id : 9d8711ec-f1b4-45e4-8072-2b3aa49793f0
- grant_type : client_credentials
- scope : manageRegistration
NB : L’appel aux ressources de l’API se fait sur une session sécurisée TLS1.2 avec authentification mutuelle par certificat QWAC dans cet appel.
Réponse :
{
« access_token » : « KXyZabcdefghijklmopqrstuvw1234567890 »
}
Une fois le jeton d’accès reçu, les méthodes accessibles sont les suivantes :
| MÉTHODE | PATH | DESCRIPTION / CAS D’USAGE |
| POST | /register | 1 – Demande d’enregistrement du TPP |
| PUT | /register/${client_id} | 2 – Modification des données de l’enregistrement |
| GET | /register/${client_id} | 3 – Récupération des données d’enregistrement |
| DELETE | /register/${client_id} | 4 – Suppression des données de l’enregistrement |
Auto-enrôlement des données
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité.
Requête POST /register
Exemple (sandbox) : POST https://www.17515.sandbox.api.89C3.com/stet/setting/v1/register (voir le swager « setting » dans documentation)
Paramètres :
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 | 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 registration requests must also provide a signature, the TPP must sign this request with the private key corresponding to the QSEALC certificate. 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)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. |
| 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. |
Réponse
Une réponse correcte retourne le statut HTTP 201. Le TPP recevra aussi son nouvel client_id qui devra être utilisé dans tous les appels des API DSP2.
Erreurs
| 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. |
Modification des données
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité.
Pour modifier les données d’enregistrement d’une application consommatrice des API DSP2, le « client_id » permettant d’interroger cette méthode est récupéré via le résultat de la requête POST /register.
Requête PUT /register/{client_id}
Exemple (sandbox) : PUT https://www.17515.sandbox.api.89C3.com/stet/setting/v1/register/AGTFR-ACPR-12345001 (voir le swager « setting » dans documentation)
avec le client_id récupéré dans la réponse de l’enrôlement (cf. la méthode POST /register).
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.
(*) 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 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. |
Réponse
Une réponse correcte retourne le statut HTTP 201.
Erreurs
| 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. |
Récupération des données
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité.
Pour modifier les données d’enregistrement d’une application consommatrice des API DSP2, le « client_id » permettant d’interroger cette méthode est récupéré via le résultat de la requête POST /register.
Requête GET /register/{client_id}
Exemple (sandbox) : GET https://www.17515.sandbox.api.89C3.com/stet/setting/v1/register/AGTFR-ACPR-12345001 (voir le swager « setting » dans documentation)
avec le client_id récupéré dans la réponse de l’enrôlement (cf. la méthode POST /register).
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. |
Réponse
Une réponse correcte retourne le statut HTPP 200.
Erreurs
| 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. |
Suppression des données
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité.
Pour modifier les données d’enregistrement d’une application consommatrice des API DSP2, le « client_id » permettant d’interroger cette méthode est récupéré via le résultat de la requête POST /register.
Requête DELETE /register/{client_id}
Exemple (sandbox) : DELETE https://www.17515.sandbox.api.89C3.com/stet/setting/v1/register/AGTFR-ACPR-12345001 (voir le swager « setting » dans documentation)
avec le client_id récupéré dans la réponse de l’enrôlement (cf. la méthode POST /register).
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. |
Réponse
Une réponse correcte retourne le statut HTTP 204.
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. |
Historique des versions
Version de la norme STET utilisée pour l’API
Cette API REST est conforme à la spécification interbancaire française STET (https://www.stet.eu/en/psd2/), version v.1.4.2.17, afin de répondre aux exigences règlementaires de la DSP2. Elle tient compte des limitations fonctionnelles aux Banques Palatines décrites dans la section « Limitations ». Elle tient compte des limitations fonctionnelles propres aux Banques Palatines.
Pour rappel :
- les textes de la directive de paiement numéro 2 (DSP2, référence UE 2015/2366 du 25/11/2015) sont rentrés en application le 13 janvier 2018 : http://eur-lex.europa.eu/legal-content/FR/TXT/?uri=CELEX:32015L2366
- ils ont été complétés par les normes techniques de réglementation (NTR, règlement délégué UE 2018/389) relatives à l’authentification forte du client et à des normes ouvertes communes et sécurisées de communication dont la date d’application se situe au 14 septembre 2019. Ces normes sont les RTS (Rules Technical Standards) : https://eur-lex.europa.eu/legal-content/FR/TXT/?toc=OJ%3AL%3A2018%3A069%3ATOC&uri=uriserv%3AOJ.L_.2018.069.01.0023.01.FRA
En France, l’ordonnance n° 2017-1252 du 9 août 2017 transpose la directive DSP2 dans la partie législative du code monétaire et financier. L’ordonnance est complétée au plan réglementaire par les décrets n° 2017-1313 et n° 2017-1314 du 31 août 2017 et les cinq arrêtés du 31 août 2017.
Vous pouvez aussi consulter l’assistant virtuel au sujet des spécifications STET.
Description du support utilisateur + durée de support
Conformément à l’article 30 (5) des RTS, une assistance pour les prestataires PSP tiers est mise à disposition. Ce support utilisateur est accessible via le formulaire sur ce portail BPCE API, ou via https://www.api.89c3.com/fr/nous-contacter. Les réponses se font pendant les heures de travail ouvrées.
Les utilisateurs peuvent également consulter l’assistant virtuel en cliquant sur le pictogramme sur la page d’accueil du portail.
Afin d’interroger une API, la version de l’API inclut le numéro de version dans l’URI appelée, soit par exemple : /stet/psd2/v1.4.2/register.
Le cas d’usage « Roadmap » donne la table de correspondance entre la version de l’API et la version de la spécification utilisée, soit par exemple la v1.4.2 de l’API qui correspond à la version v1.4.2.17 des spécifications STET.
Le principe de la durée de support est schématisée ci-dessous en prenant en compte l’article 30 (4) des RTS :
Evolutions importantes apportées depuis la première version livrée
| CAS D’USAGE / MÉTHODE(S) | DATE D’EFFET | DESCRIPTION DE L’ÉVOLUTION |
| Toutes | 17/03/2021 | Clarifications éditoriales |
Roadmap
Politique de décommissionnement des versions de l’API
La politique du décommissionnement est fonction du cycle de vie des API, elle-même calée sur les versions des spécifications STET. Elle est schématisée ci-dessous pour la version N :
Il est prévu une phase de tuilage entre les version majeures d’API (évolutions fonctionnelles majeures en version N+1 ou supérieures non présentes en version N).
La communication du décommissionnement d’une version N se fera à la date de déploiement de la version N+1. Le canal de communication privilégié est le portail BPCE API dans la partie « roadmap » de l’API impactée. Une communication via courriel vers les correspondants des prestataires enrôlés sur le portail BPCE API pourra venir compléter ce dispositif.
Planning des évolutions fonctionnelles à venir de l’API
L’API d’Information sur compte fait l’objet d’améliorations et d’évolutions continues tout au long de l’année. Retrouvez ci-dessous notre roadmap prévisionnelle.
| VERSION DE L’API | VERSION DE LA NORME STET | FONCTIONNALITÉS | 
SANDBOX DATE DE DÉPLOIEMENT BPCE API DEV PORTAL & SANDBOX |
LIVE DATE DE DÉPLOIEMENT BPCE LIVE API GATE WAY |
DATE DE DÉCOMMISSIONNEMENT |
| v1.4.2 | v1.4.2.17 |
|
Mars 2021 | Mars 2021 | (à définir) |
Limitations
Limitations fonctionnelles
Cette API ne pourra pas être utilisée pour modifier un profil TPP (avec app consommatrice, ulr de redirection, etc…) existant et réalisé au travers du processus de « GoLive » via notre portail BPCE API.
Par exemple, en cas de rajout d’une url de redirection, ou de remplacement d’un certificat eIDAS QWAC arrivant à expiration, tout nouveau TPP pourra effectuer cette modification de manière autonome en :
- utilisant cette API REGISTER
- recevant un nouvel « client_id » (sur base de l’OID du TPP avec un format étendu) afin de consommer les ressources des API DSP2 exposées
NB 1: Un agent qui n’a pas son propre OID ni son jeu de certificats eIDAS ne pourra pas utiliser directement cette API. Ce sera au TPP (auquel est adossé l’agent) de l’utiliser sur base de son OID et ses propres certificats eIDAS pour y déclarer l’app consommatrice de/pour son agent.
NB 2: pour un TPP qui a déjà une app consommatrice enrôlée via le portail, les informations enregistrées via le processus de « GoLive » restent valables et ne seront pas effacées par l’API REGISTER.
NB 3: Un TPP qui a déjà été enrôlé via l’API Register et qui souhaite créer un second profil (pour obtenir un second client_ID) doit utiliser un second jeu de certificats.
Limitations Techniques
L’activation du client_id restitué suite à l’enregistrement sera finalisée à 14h00 à J+1 en jour ouvré après utilisation nominale de l’API (activation à 14h00 à J si l’enregistrement est réalisé avant 09h59), sauf si au moins un critère d’éligibilité ne peut pas s’appliquer (voir section suivante), ce qui pourra générer un délai supplémentaire.
Veuillez aussi noter que :
- les certificats eIDAS signés avec l’algorithme « rsassaPss » ne sont pas acceptés
- le jeton d’accès récupéré via POST /token a une durée de validité d’une heure.
Eligibilité
Les ressources de cette API ne peuvent être consommées que si vous avez obtenu le statut de Prestataires de Services de Paiement (PSP). Ce statut est délivré par les autorités financières du pays dans lequel la demande est effectuée ; en France il s’agit de l’Autorité de Contrôle Prudentiel et de Résolution (ACPR), liée à la Banque de France.
L’obtention et la conservation d’un agrément relèvent de procédures rigoureuses afin d’apporter des garanties fortes aux utilisateurs des services de paiements, les formulaires étant disponibles sur le site de l’ACPR : https://acpr.banque-france.fr/autoriser/procedures-secteur-banque/tous-les-formulaires
Une fois l’agrément donné, le format de cet identifiant (Organisation Identifier = OID) fourni par l’autorité compétente est :
PSDXX-YYYYYYYY-ZZZZZZZZ:
XX =>code ISO 3166 du pays de l’autorité compétente
hyphen-minus « – » (0x2D (ASCII), U+002D (UTF-8))
YYYYYYYY => 2-8 caractères du l’identifiant de l’autorité compétente (A-Z, pas de séparateur)
hyphen-minus « – » (0x2D (ASCII), U+002D (UTF-8))
ZZZZZZZZ => identifiant du PSP spécifié par l’autorité nationale compétente (sans restriction sur le nombre – ou sur le type – de caractère utilisé)
Cet identifiant OID est important à 2 titres :
- il servira à vous identifier lors des appels dans les requêtes des API STET (via le paramètre « client_id ») ;
- il devra être présent dans les certificats eIDAS que vous fournirez au teneur de compte (voir ci-dessous).
De plus, vous devez disposer de certificats délivrés par une autorité de certification reconnue (Qualified Certification Service Providers – QTSP : https://webgate.ec.europa.eu/tl-browser/#/) conformes au règlement eIDAS (electronic IDentification And trust Services : https://www.ssi.gouv.fr/entreprise/reglementation/confiance-numerique/le-reglement-eidas/) et respectant la norme ETSI (https://www.etsi.org/deliver/etsi_ts/119400_119499/119495/01.02.01_60/ts_119495v010201p.pdf).
Afin de consommer les API DSP2 proposées sur le portail du groupe BPCE, vous aurez à utiliser des certificats QWAC et QSEALC valides :
- de test pour le fonctionnement de l’assemblage en sandbox ;
- de production lors du processus de demande de GO Live sur le portail BPCE API.
En cas de problème d’accès via l’API Register à cause des certificats, nous vérifierons s’ils ont été signés par une nouvelle autorité de certification, ou avec un nouveau certificat racine (d’une autorité de certification existante). Dans ces deux cas, il faudra compte un délai supplémentaire (de l’ordre de 2 semaines) pour ce chargement.
Seules les clés publiques au format .pem sont nécessaires. Des contrôles sur les données des certificats seront effectués à partir des registres Français (REGAFI : https://www.regafi.fr) et Européen (ABE ou EBA : https://euclid.eba.europa.eu/register/pir/disclaimer).
Vous pouvez également consulter l’assistant virtuel au sujet du principe de l’agrément.