Publications réglementaires

Récupérez votre jeton

L’accès aux API « information sur compte » ou « disponibilité des fonds » vous est autorisé via un jeton d’accès (access_token) qui peut être obtenu en appliquant le standard de la place OAuth2.

Cinématique de récupération du jeton d’autorisation

1. Notre client (PSU) vous indique l’identité de son établissement de compte.

2. Vous initiez la séquence de récupération du jeton d’accès OAuth2 en redirigeant le client (PSU), via son navigateur internet, vers l’infrastructure informatique d’autorisation de l’établissement teneur de compte (ASPSP) et en utilisant la commande : GET /authorize

Voir aussi la spécification de place STET V1.4.0.47 / Part I / section 3.4.3.2 / page 21

3. Le teneur de compte (ASPSP) va :

• Identifier et authentifier son client par l’une des méthodes d’authentification forte qu’elle propose et qu’il présente au client ;
• Effectuer des vérifications liées à votre profil en tant qu’AISP ou CBPII (validité de vos certificats QWAC et QSEALC et de votre rôle, non révocation de votre profil, etc.)

4. Une fois ces vérifications effectuées et si elles sont concluantes, l’établissement bancaire va rediriger le client (PSU) vers votre site en utilisant votre URL de « call-back » (redirection) que vous nous aurez transmise lors du processus de « Go Live ».

En effet, l’AISP doit préciser pour son APP consommatrice, une URL qui sera appelée par l’établissement bancaire :

• Si le PSU a autorisé la récupération de ses données par l’AISP
• Ou en cas de refus du consentement
• Ou si la cinématique d’identification et d’authentification est interrompue à l’une de ses étapes (exemple : timeout sur l’écran d’identification ou sur l’écran d’authentification forte).

Si le PSU vous a autorisé à récupérer ses données chez son teneur de compte, vous trouverez dans la réponse à cet appel un code à utilisation unique qui a une durée de vie courte.

5. Via un appel de type POST /token, vous allez pouvoir alors demander directement au teneur de compte votre jeton d’accès OAuth2(access_token) avec les éléments reçus précédemment dont le code à utilisation unique.

NB : les requêtes /token du flow Authorization Code doivent être envoyées SANS le paramètre « scope ».

Voir aussi la spécification de place STET V1.4.0.47 / Part I / section 3.4.3.2 / page 22

6. L’établissement teneur de compte (ASPSP) va :

• Effectuer des vérifications liées à votre profil en tant qu’AISP ou CBPII (validité des certificats et de votre agrément, non révocation de votre profil, etc.)
• Vous identifier et vous authentifier en tant qu’AISP ou CBPII via votre certificat que vous mettrez à disposition pour sécuriser l’échange mutuel.

7. Une fois ces vérifications effectuées et si elles sont concluantes, le teneur de compte va vous renvoyer une réponse HTTP 200 (OK) contenant, entre autres, le jeton d’accès OAuth2 (access_token).

Voir aussi la spécification de place STET V1.4.0.47 / Part I / section 3.4.3.2 / page 23

8. Dès que le jeton d’accès OAuth2 (access_token) délivré par la banque a été récupéré par vos soins, vous pourrez le présenter pour pouvoir consommer les ressources de l’API.

Ce jeton est accompagné d’un refresh_token valable 180 jours que vous devez conserver. Lorsque votre access_token arrive à expiration, vous pouvez en redemander un nouveau en suivant la rubrique « Vue d’ensemble » > « Rafraîchir votre jeton« .

Au bout de 180 jours votre refresh_token arrive à expiration. Pour en récupérer un nouveau, vous devrez reprendre cette cinématique « Récupérer votre jeton » et passer, de facto, par une nouvelle étape d’authentification forte du client auprès de son établissement bancaire (cf. point 3. ci-dessus).

Pour plus de détails, voir aussi OAuth 2.0 Authorization Framework : https://tools.ietf.org/html/rfc6749#section-4.1

 

Exemple

Un exemple de requête est fourni dans la rubrique "Testez l’API avec la sandbox".

Vérifiez la disponibilité des fonds

Ce service permet de vérifier la disponibilité des fonds pour le compte de notre client pour un montant donné d’une transaction.
 

Prérequis

Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité, d’avoir récupéré le jeton d’accès OAuth2 (voir le cas d’usage "Récupérez votre jeton" ) et de fournir les paramètres du body.
 

Requête

POST /funds-confirmations
 

Paramètres obligatoires du body requis pour l’appel de ce service

• paymentCoverageRequestId : Identifiant de la requête de paiement
• instructedAmount : La structure comprenant le montant renseigné ainsi que la devise
  • currency : Devise du montant renseigné
  • amount : Montant qui permettra de déterminer si les fonds sont disponibles
• accountId : Identifiant unique pour le compte renseigné
  • iban : Numéro de compte bancaire international (IBAN)
     

Réponse

Le résultat retourné reprendra les informations de la requête ainsi que la réponse concernant la disponibilité des fonds sous la forme d’un booléen.

Un lien self sera également présent pour revenir à la page obtenue juste après exécution de la requête.

 

Exemple

Requête

POST /v1/funds-confirmations

Body
{

« paymentCoverageRequestId » : « MyCoverage123456 »,

« instructedAmount » : {

« currency » : « EUR »,

« amount » : « 12345 » },

« accountId » : { « iban » : « YY13RDHN98392489481620896668799742 » }

}
 

Résultat

Status code : 200

Body
{

« request » : {

« paymentCoverageRequestId » : « MyCoverage123456 »,

« instructedAmount » : {

« currency » : « EUR »,

« amount » : « 12345 » },

« accountId » : {« iban » : « YY13RDHN98392489481620896668799742 » }

},

« result » : true,

« _links » : {

« self » : {

« href » : « v1/funds-confirmations »

}

}

}

Rafraîchissez votre jeton

Principe

Les jetons OAuth2 ayant une durée de vie limitée, il vous est nécessaire d’en demander le rafraîchissement avant son expiration.

Règles de base

Le teneur de compte (ASPSP) dispose au plus d’un jeton d’accès (access_token) et d’un jeton de rafraîchissement (refresh_token) valides par triplet client PSU / TPP / rôle AISP ou CBPII.

• Le jeton d’accès a une durée de validité courte (de l’ordre d’une heure max) sur un périphérique ou une application de notre client
• Le jeton de rafraîchissement a une durée de vie de 180 jours
• Le jeton de rafraîchissement et le jeton d’accès doivent pouvoir être révoqués à tout moment
• Si le jeton d’accès est révoqué alors le jeton de rafraîchissement doit l’être aussi et réciproquement

Cinématique du rafraîchissement de votre jeton d’accès (access_token)

1. Vous demandez le renouvellement du jeton d’accès auprès de l’ASPSP

2. L’ASPSP initie le renouvellement du jeton d’accès

3. L’ASPSP récupère le certificat du TPP auprès du référentiel de place

4. L’ASPSP contrôle la validité et la non révocation du certificat présenté

5. L’ASPSP contrôle la date de la dernière authentification (< 180 jours)

6. L’ASPSP vous transmet le nouveau jeton d’accès et l’ancien jeton de rafraîchissement

7. Vous stockez le jeton d’autorisation et l’ancien jeton de rafraîchissement de façon sûre

8. L’ASPSP invalide l’ancien jeton d’autorisation

Exemple

Un exemple de requête est fourni dans la rubrique "Testez l’API avec la sandbox".

Testez l’API avec la sandbox

Principe

La sandbox BPCE API peut être utilisée directement via votre application en appelant l’API « Disponibilité des fonds » de la plateforme BPCE-API : c’est le mode assemblage sandbox illustré ci-dessous et qui sera disponible sous peu.

Image

Explications

En assemblage sandbox, il y a 2 appels :

• Le premier pour récupérer le jeton d’autorisation
• Le second pour faire l’appel à l’API d’information sur compte

Votre application consommatrice de l’API « Disponibilité des fonds » de la sandbox va devoir récupérer un jeton d’accès via sa clé d’authentification auprès de l’AS (Authentification Server). Ainsi l’application pourra consommer la méthode POST /funds-confirmations grâce à son jeton d’accès.

Les données utilisées pour faire les tests seront issues des persona (voir le cas d'usage « Testez nos persona »), ce qui vous permettra de choisir des profils spécifiques de façon à mieux cibler vos tests.

Testez nos persona

Conformément à la réglementation DSP2 (cf. RTS Art. 30 (5)), nous devons, en tant qu’ASPSP, mettre à disposition un dispositif d’essai comprenant une assistance et permettant des tests de connexion et de fonctionnement afin que les TPP qui ont demandé l’agrément nécessaire puissent tester les logiciels et applications qu’ils utilisent pour proposer un service de paiement aux utilisateurs.

Il est aussi demandé l’utilisation de données fictives. C’est l’objectif de ces données de tests sous forme de « persona » qui rassemblent divers clients sur base de :

• segment de clientèle (étudiant, actif, retraité, entrepreneur individuel, etc..) ;
• caractéristiques de leurs comptes (mono-compte, multi-comptes, solde qui est statique) ;
• le consentement PSU a déjà été donné ;
• données utiles attendues en entrée par les API (identifiant banque à distance, IBAN).

Ce jeu de données évoluera au cours du temps avec rajout de données additionnelles (autres clients, nombre de transactions, profondeur d’historique). Revenez régulièrement sur cette section pour être à jour !

Les identifiants et données ci-dessous sont des données fictives et ne peuvent pas être utilisées en production.

Personas

Image	Image
LEA SANDBOXA	CLAIRE RECETTEB
Etudiante 1 seul compte de paiement (abonné PART)	Actif et entrepreneur individuel 2 comptes de paiement PART et un PRO/EI (abonné PART)
Image	Image
GEORGES PERSONAC	GILLES TESTUNID
Actif 1 seul compte joint de paiement Mr OU Mme (abonné PART) 200 transactions disponibles sur l’IBAN FR7617515000920400085945890	Retraité 3 comptes de paiement PART (abonné PART) : Mr, Mr OU Mme, Mr ET Mme

NB : pour tous ces personas, il vous faudra saisir le code SMS = « 12345678 » dans l’écran d’authentification proposé en mode assemblage.
 

ATTENTION : NOUVEAUX IDENTIFIANTS

Utilisez le fallback

Principe

Conformément à la réglementation, les établissements du groupe BPCE ont mis en place une interface dédiée aux prestataires de services de paiement : il s’agit des API REST DSP2 publiées.

Si les API DSP2 exposées sont défaillantes, le prestataire des services de paiement pourra utiliser la solution couvrant les « mesures d’urgence applicables à une interface dédiée » (ou « fallback ») dont le principe est le suivant :

Image

Cette solution répond aux exigences réglementaires de la DSP2 (article 33 des RTS). Vous pourrez l’utiliser avec les mêmes conditions et prérequis décrits dans la rubrique "Eligibilité".

 

 

Roadmap

Retrouvez ci-dessous les éléments de notre trajectoire prévisionnelle :

Version	Fonctionnalités	Sandbox   Image Date de déploiement BPCE API Dev Portal & Sandbox	Live   Image Date de déploiement BPCE Live API Gateway
v1.0	Fallback (*)	Non applicable	Fin Septembre 2019

(*) Fonctionnalités Principales :

• Utilisation par le TPP du même endpoint que l’interface dédiée. Il dépend donc du code établissement qui permet d’adresser le bon référentiel client. La liste de nos établissements et les valeurs possibles sont précisées dans la rubrique "Limitations".
   
• Un paramètre de requête (header « fallback:1 » présent ou absent) ajouté par le TPP permet de distinguer une requête « fallback » d’une requête API via l’interface dédiée qui doit être utilisée systématiquement.
   
• Authentification du TPP via authentification mutuelle TLS par un certificat eIDAS (QWAC).
   
• Sécurisation identique à celle d’un accès à la banque en ligne du PSU (même interface utilisée par le PSU qu’en accès direct, et mêmes moyens d’authentification du client).
   
• Dans le cadre de la montée en charge de l’usage de l’interface dédiée (API), il n’est pas mis en place de bascule dynamique : la solution fallback est toujours active.
   
• La solution de fallback est une solution de secours ne devant pas être utilisée comme moyen principal d’accès pour proposer les services DSP2. Son usage en est monitoré et tout usage abusif par un/des TPP sera automatiquement reporté auprès de l’autorité nationale compétente.

 

Exemple

1. Dans le cas où les API DPS2 sont indisponibles de façon imprévue ou le système tomberait en panne (voir critères dans le texte RTS Art. 33), le TPP peut alors envoyer la requête :

POST https://www.<codetab>.oba-bad-me-live.api.89c3.com/stet/psd2/oauth/token(nouvelle url à prendre en compte dès à présent)
(Pour rappel, l’url 89C3 existante www.<codetab>.live.api.89C3.com ne sera plus disponible à partir du 28/09/2025)

avec <codetab> =

• 17515 pour Caisse d’Epargne

avec :

• son certificat eIDAS QWAC de production
• le paramètre header (fallback: "1")

Image

2. Si les vérifications sont positives, l’url de redirection (permettant d’afficher la page d’accès à la banque en ligne) et le jeton JWT seront dans le header de la réponse.
 

3. Le TPP doit utiliser ensuite les identifiants du PSU via sa méthode propriétaire

Pour plus de détails sur la requête POST, voir STET V1.4.0.47 / Part I / section 3.4.3.2 / page 22

 

Limites

Les contraintes de cette solution sont les suivantes :

• Pas de réutilisation du contexte de l’interface dédiée, ni du jeton d’accès valable 180 jours (AISP)
   
• L’identifiant du terminal accédant (TermId) doit être obligatoirement fourni, sinon l’accès aux pages d’identification/authentification sera bloqué
   
• Seules les fonctionnalités DSP2 présentes sur la banque en ligne (référence : banque à distance sur internet fixe – pas la banque sur mobile) sont accessibles via le fallback. Par exemple, les services de banque en ligne ne proposent pas de paiement e-commerce. Cette fonctionnalité PISP n’est donc pas disponible en mode fallback.
   
• Le client utilisateur des services (PSU) doit être connecté à l’app du TPP (pas de possibilité de traitement batch AISP pour venir récupérer les données consenties du client). La DSP2 imposant également un renforcement des moyens d’authentification forte (AF/SCA) systématique pour les accès à la banque à distance/en ligne, les moyens d’authentification fournis aux clients PSU seront utilisés (liste non exhaustive) :
  • Soft token
  • OTP SMS
  • Clé physique (pour les entreprises)

 

Planning des évolutions fonctionnelles à venir de l’API

(*) Fonctionnalités Principales :

• Obtention de l’information demandée sous forme OUI/NON ;
• Pas de blocage des fonds par le teneur de compte ;
• Pas de différence entre les versions V1 et V1.4.2 et V1.6.2

Politique de décommissionnement des versions de l’API

La politique du décommissionnement (= arrêt d’une version d’une API sur les environnements de production et sandbox) est fonction du cycle de vie des API, et il est prévu une phase de tuilage entre deux versions majeures d’API comme indiqué dans le schéma ci-dessous :

Image

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.

Limitations fonctionnelles

Les limitations de cette API DSP2 sont les suivantes :

• Ne s’applique qu’aux comptes de paiements en euros, éligibles (non bloqué ou sous séquestre) et accessibles en ligne (cf. texte de la Directive DSP2) et consentement PSU fourni.
   
• Ne couvre que les segments des particuliers (compte de dépôt) et professionnels/entrepreneurs individuels (compte courant). A terme, d’autres segments clients seront disponibles.
   
• N’utilise que le mode d’authentification par redirection (Authentification Forte du client demandée et gérée via la banque).
   
• Ne permet l’accès que via l’IBAN du compte de paiement (et non via l’identifiant de l’instrument de paiement).

Accès aux données de production

Pour accéder aux données réelles, veuillez utiliser auparavant notre API "DSP2 Register".

Comme en mode test, le code établissement (voir ci-dessous) vous permettra d’adresser le bon référentiel client via un point d’accès au format :

www.<cdetab>.oba-bad-me-live.api.89c3.com (nouvelle url à prendre en compte dès à présent)
(Pour rappel, l’url 89C3 existante www.<codetab>.live.api.89C3.com ne sera plus disponible à partir du 28/09/2025)

Exemples :

• STET V1.4.0 POST https://www.17515.oba-bad-me-live.api.89c3.com/stet/psd2/v1/funds-confirmations ( /!\ scope = piisp )
• STET V1.4.2 POST https://www.17515.oba-bad-me-live.api.89c3.com/stet/psd2/v1.4.2/funds-confirmations ( /!\ scope = cbpii )
• STET V1.6.2 POST https://www.17515.oba-bad-me-live.api.89c3.com/stet/psd2/v1.6.2/funds-confirmations ( /!\ scope = cbpii )

Image

Eligibilité

Les ressources de l’API "Disponibilité des fonds" ne peuvent être consommées que par des PSP ayant le rôle de Prestataires de Services d’initiation de Paiement (PISP). 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 ce portail, le TPP doit enrôler son app et nous transmettre via notre API DSP2 Register des certificats de production signés par une autorité de certification agréée :

• un premier jeu de certificats QWAC (pour l’authentification mutuelle TLS) et QSEALC (à charger sur notre passerelle via l’API Register) pour la sandbox
• un autre jeu de certificats QWAC (pour l’authentification mutuelle TLS) et QSEALC (à charger sur notre passerelle via l’API Register) pour la production

NB IMPORTANT : en cas de renouvellement de certificat, et si l’autorité de certification (QTSP) est différente (ou c’est la même entreprise QTSP mais qui utilise des clés racines différentes), le TPP doit avertir le support API disponible via ce site de 2 mois avant à toutes fins de vérifier que les éléments de la nouvelle autorité de certification sont bien chargés sur nos infrastructures.

Un identifiant keyID devra aussi être fourni dans un format conforme à la spécification STET intégrant une empreinte SHA256 après le caractère « _ » char, voir exemple dans la documentation STET Part 3 / Interaction Examples : keyId=https://path.to/myQsealCertificate_612b4c7d103074b29e4c1ece1ef40bc575c0a87e.
 

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).