Consommer l'API

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.6.2/accounts.
 

La description des services proposés ci-après n’est que purement fonctionnelle. Les aspects techniques sont répertoriés dans la rubrique « Cas d’usage » qui sont plus détaillées.

Vous devez aussi être familier avec la terminologie DSP2 et les abréviations utilisées. Vous pouvez également utiliser la foire aux questions (FAQ).

Pour rappel, il faudra que le prestataire agréé DSP2 :

• exécute une authentification mutuelle avec vos certificats
• fasse une demande de jeton d’accès (Oauth2) via le mode « redirection »
• récupère la liste des comptes courants
• demande le consentement client et le transmettre au teneur de compte (ASPSP).

Une fois fait, l’objectif de cette API concerne l’obtention d’informations consenties en fonction des choix du client sur son ou ses comptes de paiement :

• Le solde
• et/ou l’historique des transactions (avec les détails si disponibles)
• et/ou le nom et prénom du client connecté
• et/ou le découvert autorisé

Certains de ces services peuvent présenter des limitations : s’ils ne sont pas proposés via la banque à distance, ils ne le seront pas via cette API (voir la rubrique « Limitations« ), ce qui est le cas par exemple des deux derniers services listés ci-dessus.

Dans l’environnement d’assemblage/sandbox, l’accès aux données de tests se fait via le point d’entrée www.<codetab>.sandbox.api.89C3.com (voir la rubrique « Comment tester l’API ? »).

Dans l’environnement de production, l’accès aux données de production se fait via le point d’entrée www.<codetab>.oba-bad-me-live.api.89C3.com (nouvelle url à prendre en compte dès à présent)
ou en remplaçant « 89c3.com » par le nom de domaine web du teneur de compte (voir la rubrique « Limitations »).
(Pour rappel, l’url 89C3 existante www.<codetab>.live.api.89C3.com ne sera plus disponible à partir du 28/09/2025)
 

Obtenir la liste des comptes d’un client

Description

Ce premier appel permet de récupérer la liste des comptes du client usager d’un service de paiement (PSU) chez le teneur de compte (ASPSP) pour lequel le TPP (AISP) est connecté.

Prérequis

• Le TPP est présent dans le référentiel des tiers agréés avec un rôle d’AISP
• Le TPP et le PSU sont liés à l’ASPSP par un contrat
• Lors de cette étape, un jeton d’autorisation OAuth2 (ou token d’accès) a été délivré au TPP par l’ASPSP (voir le cas d’usage technique associé)
• Le TPP et l’ASPSP se sont mutuellement contrôlés et authentifiés
• Le TPP a fourni son jeton d’autorisation à l’ASPSP pour pouvoir consommer les ressources de cette API

Echange de données

Le TPP envoie une requête GET à l’ASPSP pour récupérer la liste des comptes du PSU. L’ASPSP obtient cette liste en retour et la présente au client afin que celui puisse choisir les comptes et données auxquels il autorise l’accès (voir le cas d’usage technique associé).

Enregistrer le consentement d’un client (AISP)

Description

Cette seconde requête rendue obligatoire par le teneur de compte (ASPSP) permet de lui transmettre la liste des comptes et des données consenties afin qu’il puisse enregistrer ces informations du client (PSU) pour lequel le prestataire de service (AISP) est connecté.

Ce consentement contient le détail des accès consentis par le PSU à l’AISP.

Un enregistrement du consentement est donc réalisé pour un PSU donné, un AISP donné, une opération donnée et un compte donné.

Chaque nouvel appel de l’AISP au service d’enregistrement du consentement pour un PSU donné, annulera et remplacera le consentement précédent le cas échéant.

Par ailleurs, à la demande du PSU, le consentement pourra être modifié ultérieurement par type d’opération : par exemple, le consentement pour l’accès à l’historique des transactions peut être révoqué alors que le consentement pour les soldes reste actif.

Prérequis

Le TPP a présenté une première demande de récupération de la liste des comptes d’un PSU et les a présentés au client pour finaliser son consentement.

Le PSU communique à l’AISP la liste des comptes et des fonctionnalités pour lesquels un consentement est donné.

Echange de données

L’AISP transmet ces informations à l’ASPS via une requête PUT en incluant la liste des comptes et des données consenties par le PSU (voir le cas d’usage technique associé).

Obtenir le solde d’un compte

Description

Cet appel permet de récupérer le solde comptable (« CLBD » dans la norme STET) d’un compte du PSU pour lequel l’AISP est connecté.

Prérequis

Le TPP aura récupéré auparavant la liste des comptes disponibles pour le PSU et a transmis les informations consenties à l’ASPSP.

Echange de données

L’AISP sollicite l’ASPSP pour l’un des comptes consentis du PSU et demande le solde.

L’ASPSP doit fournir au minimum le solde comptable du compte (voir le cas d’usage technique associé).

Obtenir la liste des transactions d’un client

Description

Cet appel permet de récupérer la liste des opérations d’un compte du PSU pour lequel l’AISP est connecté, ainsi qu’éventuellement leurs détails

La profondeur d’historique remontée par rapport à la date du jour de la requête API dépend de l’abonnement de la banque en ligne du client.

Prérequis

Le TPP aura récupéré auparavant la liste des comptes disponibles pour le PSU et a transmis les informations consenties à l’ASPSP.

Echange de données

L’AISP sollicite l’ASPSP pour l’un des comptes de paiements du PSU. Il peut fournir certains critères de sélection.

L’ASPSP répond avec une liste de transactions correspondant à la requête (voir le cas d’usage technique associé).

Récupérer l’identité du client connecté

Description

Cet appel permet de récupérer l’identité du client connecté.

Prérequis

Le TPP aura transmis les informations consenties à l’ASPSP.

Echange de données

L’AISP sollicite l’ASPSP pour l’un des comptes de paiements du PSU.

L’ASPSP répond avec la donnée consentie (voir le cas d’usage technique associé).

Récupérer le découvert autorisé du client

Description

Cet appel permet de récupérer le montant du découvert autorisé du client.

Prérequis

Le TPP aura récupéré auparavant la liste des comptes disponibles pour le PSU et a transmis les informations consenties à l’ASPSP.

Echange de données

L’AISP sollicite l’ASPSP pour l’un des comptes de paiements du PSU.

L’ASPSP répond avec la donnée consentie (voir le cas d’usage technique associé).

Utiliser 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 l’infrastructure de production « passerelle BPCE API Live » exposant les API DSP2 est défaillante, le prestataire des services de paiements 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 :

(*) Fonctionnalités Principales :

• Utilisation par le TPP du même endpoint que l’interface dédiée.
• 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 indisponible 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 :

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

Image

POST /stet/psd2/oauth/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

X-Request-ID: 1234

fallback: 1

User-Agent: PostmanRuntime/7.16.3

Accept: */*

Cache-Control: no-cache

Host: www.17515.live.api.caisse-epargne.fr

Accept-Encoding: gzip, deflate

Content-Length: 67

Connection: keep-alive

client_id=PSDFR-ACPR-12345&grant_type=client_credentials&scope=aisp

2. Si les vérifications sont positives, nous allons vous renvoyer dans le header une url de type à utiliser dans le cadre de la redirection vers l’environnement de la banque en ligne, et qui contient un jeton JWT (champs « &fallback= ») qui doit être aussi utilisé dans ce cadre :

HTTP/1.1 302 Found

Date: Tue, 25 May 2021 21:46:59 GMT

Location: https://www.caisse-epargne.fr/se-connecter/sso?service=dei&cdetab=17515&fallback=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImhF…

Content-Length: 870

Connection: close

Content-Type: text/html; charset=iso-8859-1

</head><body>

<h1>Found</h1>

<p>The document has moved <a href= »/www.17515.live.api.caisse-epargne.fr&fallback=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImhF… »>here</a>.</p>

</body></html>

3. Une fois redirigé, 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 spécifications STET 

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 actuellement)
• Seules les fonctionnalités DSP2 présentes sur la banque en ligne (référence: banque à distance sur internet fixe) 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’application 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 Sécur’Pass
  • OTP SMS
  • Clé physique (pour les entreprises)

Activer l'App2App

Introduction

Cette fonctionnalité permet d’activer automatiquement l’app bancaire du client à toutes fins d’identification et d’authentification.

Prérequis

Le client doit avoir chargé et utilisé au moins une fois la dernière version de l’application bancaire sur les magasins d’applications Android et Apple (version V6.4.0 et plus).

Note : les segment clients PRO & ENT ne sont pas activés

Le lien de retour (Universal link) doit être définie en avance par le TPP sur le même principe qu’une url de callback :

• si ce lien / cette url a déjà été déclarée sur notre passerelle BPCE API, il n’y a rien d’autre à faire
• sinon le TPP doit le déclarer en utilisant notre API Enregistrement DSP2

Nos liens « Universal links » ont été déclarés sur les plateformes iOS et Android. Ce n’est pas la peine d’y accéder via par exemple https://www.<codetab>.live.api.caisse-epargne.fr/89C3api/accreditation/v2/.well-known/apple-app-site-association qui renverra une erreur.

Requête

L’activation de la fonctionnalité App2App s’effectuera en production via l’envoi d’une requête par l’app du TPP au format STET suivant :

Sinon, une webview sera affichée via le navigateur du smartphone du client dans les cas suivants :

• si l’app bancaire n’est pas chargée sur le smartphone du client

ou

• si l’app bancaire chargée n’est pas compatible avec l’App2App (voir les prérequis)

ou

• si l’autre format d’appel des point d’accès a été utilisé http://www.<codetab>.oba-bad-me-live.api.89c3.com/stet/psd2/oauth/authorize (nouvelle url à prendre en compte dès à présent)
  (ce qui peut être utile comme backup en cas de problème avec l’App2App)
  (Pour rappel, l’url 89C3 existante www.<codetab>.live.api.89C3.com ne sera plus disponible à partir du 28/09/2025)

Publications réglementaires

Récupérer votre jeton

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

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

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

2. Le TPP initie 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 

3. Le teneur de compte (ASPSP) va :

• Identifier et authentifier son client via l’une des méthodes d’authentification forte dont il a été équipé
• Effectuer des vérifications liées au TPP

4. Une fois ces vérifications effectuées, et si elles sont concluantes, l’établissement bancaire va rediriger le client (PSU) vers le site du TPP en utilisant l’URL de « call-back » (redirection) transmise lors de l’enrôlement.

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 a autorisé le TPP à récupérer ses données chez son teneur de compte, le TPP trouvera dans la réponse à cet appel un code à utilisation unique avec une durée de vie courte.

5. Via un appel de type POST /token, le TPP pourra alors demander directement au teneur de compte son 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ée SANS le paramètre « scope ».

Voir aussi la spécification de place STET

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

• Effectuer des vérifications liées à au profil du TPP en tant qu’AISP ou CBPII (validité des certificats et de l’agrément, non révocation, etc.)
• identifier et authentifier le TPP via le certificat QWAC envoyé pour sécuriser l’échange mutuel (validité des certificats, rôle, non révocation de votre profil, etc.)

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, entres autres, le jeton d’accès OAuth2 (access_token).

Voir aussi la spécification de place STET 1.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 le TPP, il pourra le présenter pour pouvoir consommer les ressources de l’API.

Ce jeton est accompagné d’un refresh_token qui est à conserver. Lorsque l’access_token arrive à expiration, le TPP pourra en redemander un nouveau en suivant la rubrique « Cas d'usage » > « Rafraîchir votre jeton » .

Au bout du délai réglementaire indiqué dans le jeton, le refresh_token arrive à expiration. Pour en récupérer un nouveau, le TPP devra 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 « Comment tester l’API ? » > « Assemblage sandbox ».

Obtenir la liste des comptes

Ce service permet de lister tous les comptes éligibles* à la DSP2.

NB (*) : comptes de paiements actifs et accessibles en ligne, soit des comptes de dépôt pour les clients particuliers, et des comptes courants pour les professionnels et entreprises.

Prérequis

Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité et d’avoir récupéré le jeton d’accès OAuth2 (voir la rubrique « Cas d'usage » > « Récupérer votre jeton » ).

Requête

Requête « GET /accounts« 

Voir aussi la spécification de place STET 

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

Aucun paramètre spécifique n’est requis pour l’appel de ce service.

Résultat retourné

En cas de première utilisation de cette requête (et donc si vous n’avez pas transmis au préalable d’information via la méthode PUT /consents), ou que tous les comptes consentis ont été révoqués suite à une appel avec la méthode PUT /consents à blanc (= pas de compte consenti transmis) :

• Cet appel permet au TPP de récupérer la liste de tous les comptes éligibles* DSP2 du client sans les données ou liens associées (= sans les URI pour les méthodes GET /balances, GET /transactions, etc …)
   

Si vous avez transmis au préalable au moins un compte consenti par le client via la méthode PUT /consents, et qu’il n’a pas été révoqué avec la méthode PUT /consents à blanc (= pas de compte consenti transmis), alors cet appel :

• permet de récupérer la liste de tous les comptes consentis du client détenteur avec :
  • L’URI pour la méthode GET /balances si le/les IBAN font partie de la liste « balances » transmise via la méthode PUT /consents
  • L’URI pour la méthode GET /transactions si le/les IBAN font partie de la liste « transactions » transmise via la méthode PUT /consents + un lien self pour le détail des transactions  /!\ nouveauté V1.6.2
  • L’URI pour la méthode GET /overdrafts si le/les IBAN font partie de la liste « overdrafts » transmise via la méthode PUT /consents   /!\ nouveauté V1.6.2
• permet de récupérer les nouveaux comptes (sans les données, cf. premier appel ci-dessus) sans avoir à effectuer un PUT /consents à blanc /!\ nouveauté V1.6.2
• ne vous permet pas de récupérer les informations pour les comptes non consentis ou non éligibles DSP2 (par exemple les comptes d’épargne)

Vos accès à cette méthode sont limités à 4 accès batch maximum par jour, pour un client donné / un compte donné / par ASPSP / par TPP . En revanche, le nombre d’accès n’est pas limité lorsque c’est le client connecté qui interroge directement ses comptes.

Exemple

Un exemple de requête est fourni dans la rubrique « Comment tester l’API ? » > « Assemblage sandbox ».

Les jeux de données de tests sont décrits dans la rubrique « Comment tester l’API ? » > « Tester nos persona ».

Remarque :

• Le champ « currency » a été déplacé au niveau de l’ « accountId ».

Voir aussi la spécification de place STET 

Tests d’acceptance

Ces cas de tests ont pour objectif de vous permettre d’effectuer un minimum de tests afin de prendre en main cette API et d’y accéder depuis votre application.

Ils devront être validés avant tout déploiement applicatif en production.

Le scope OAuth2 = aisp sauf indication contraire.

Gestion du consentement

Ce service obligatoire (via le « consentement mixte AISP » imposé) permet au TPP de transmettre à la banque (ASPSP) les comptes pour lesquels son détenteur (PSU) a consenti la consultation en détails d’un certain nombre d’informations (soldes et / ou des transactions et / ou identité et/ou découvert autorisé).

Prérequis

Il est nécessaire de remplir les prérequis d’éligibilité et d’avoir récupéré le jeton d’accès OAuth2 (voir la rubrique « Cas d'usage » > « Récupérer votre jeton » ).

Le TPP peut récupérer la liste des comptes de paiements éligibles DSP2 du client après avoir appelé une première fois la requête GET /accounts : l’IBAN associé à chaque compte, c’est à dire « accountId »: {« iban »: » » }, y sera inclus.

Cependant, si le TPP connait déjà le ou les IBAN des comptes de paiements du client, il peut les transmettre directement à l’ASPSP via la méthode PUT /consents.

ATTENTION : tant que le TPP n’aura pas communiqué au teneur de compte (ASPSP) au moins un compte consenti avec la méthode PUT /consents, ou si aucun compte n’est consenti, la méthode GET /accounts ne restituera pas les informations demandées, mais uniquement la liste de tous les comptes éligibles DSP2 (principe du « consentement mixte AISP »).

Requête

Requête « PUT /consents« 

Voir aussi la spécification de place STET

Cet appel nous permettra d’enregistrer les comptes que notre client vous a consenti pour le rôle « AISP ». Notre client peut vous consentir 4 types d’accès :

• « balances » => accès aux soldes d’un ou plusieurs comptes : le solde est accessible via la méthode GET /balances pour les comptes consentis uniquement
• « transactions » => accès à l’historique des transactions d’un ou de plusieurs comptes : les transactions sont accessibles via la méthode GET /transactions pour les comptes consentis uniquement, ainsi que le détail si disponible (lien URI inclus)
• « psuIdentity » => accès à l’identité du client connecté (nom et prénom pour un client de type « particulier », ou la raison sociale pour une personne morale)
• « overdrafts » => accès au découvert client autorisé sur son compte
• « trustedBeneficiaries » : cette fonctionnalité n’est pas gérée (quelque soit la valeur de ce champs, elle n’est pas prise en compte)
• « owners  » : cette fonctionnalité n’est pas gérée (quelque soit la valeur de ce champs, elle n’est pas prise en compte)

Il est possible d’appeler plusieurs fois la méthode PUT /consents si le client a modifié son consentement via le TPP : chaque nouvel appel de la méthode PUT /consents remplace les consentements précédents.

Par ailleurs, à la demande du client, le consentement pourra être modifié ultérieurement par type d’opération : par exemple, le consentement pour l’accès à l’historique des transactions peut être révoqué alors que le consentement pour le solde reste actif.

ATTENTION :

• Si vous ne transmettez aucun compte via la méthode PUT /consents, alors que des comptes avaient été consentis via le dernier appel à cette méthode, cela signifie que le client a révoqué tous les comptes consentis
• Si aucun compte n’est consenti ou si le client a révoqué tous les comptes consentis, la méthode GET /accounts vous permet de récupérer la liste de tous les comptes, mais l’accès aux données (par exemple solde et à l’historique des transactions) n’est pas/plus possible.

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

• balances : tableau obligatoire (qui peut être vide, ou avec un/des Numéro de compte bancaire international IBAN) pour obtenir la liste des comptes accessibles pour la fonctionnalité « soldes »
• transactions : tableau obligatoire (qui peut être vide, ou avec un/des Numéro de compte bancaire international IBAN) pour obtenir la liste des comptes accessibles pour la fonctionnalité « transactions »
• overdrafts : tableau obligatoire (qui peut être vide, ou avec un/des Numéro de compte bancaire international IBAN) pour la fonctionnalité « découvert »
• psuIdentity : champs obligatoire, la valeur (true ou false) indiquant si l’accès à l’identité du client (prénom, nom) est autorisé pour l’AISP par le client
• trustedBeneficiaries : champs obligatoire, quelque soit la valeur de ce champs (true ou false), elle n’est pas prise en compte
• owners : champs obligatoire, quelque soit la valeur de ce champs (true ou false), elle n’est pas prise en compte
• PSU-IP-ADDRESS : paramètre facultatif à alimenter que si le client est connecté

Résultat retourné

Status code « 201 – Created » lors de l’enregistrement du consentement

Status code « 204 – No Content » méthode non supportée

Status code « 403 – Forbidden » en cas d’échec de l’enregistrement

Exemple

Un exemple de requête est fourni dans la rubrique « Comment tester l’API ? » > « Assemblage Sandbox ».

Les jeux de données de tests sont décrits dans la rubrique « Comment tester l’API ? » > « Tester nos persona ».

Voir aussi la spécification de place STET

Tests d’acceptance

Ces cas de tests ont pour objectif de vous permettre d’effectuer un minimum de tests afin de prendre en main cette API et d’y accéder depuis l’application du TPP.

Ils devront être validés avant tout déploiement applicatif en production.

Le scope OAuth2 = aisp sauf indication contraire.

Obtenir le solde

Ce service permet de récuperer le solde d’un compte de paiement d’un client qui a donné son consentement au TPP pour pouvoir y accéder.

Ce type de compte est soit un compte de dépôt pour les particuliers, soit un compte courant pour les professionnels et les personnes morales.

Prérequis

Pour récupérer le solde d’un compte :

• L’IBAN du compte doit nous avoir été transmis dans la liste « balances » de la méthode PUT /consents et ne doit pas avoir été révoqué depuis (<=> pas d’annule et remplace via PUT /consents sans cet IBAN dans la liste « transactions »)
• L’ »accountResourceId » permettant d’interroger cette méthode pour ce compte courant, est récupéré via le résultat de la requête GET /accounts dans la rubrique « resourceId » pour le compte correspondant à cet IBAN, c’est-à-dire tel que « accountId »: {« iban »: » » }
• L’URI pour l’accès à cette méthode est donnée via la rubrique « _links »: {« balances »: »{« href »: …}} en résultat de la requête GET /accounts pour le « resourceId » du compte

Requête

Requête « GET /accounts/{accountResourceId}/balances »

Voir aussi la spécification de place STET 

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

Paramètre accountResourceId : obligatoire (compte pour lequel le solde doit être consulté).

• Cette donnée correspond à la rubrique « resourceId » obtenue dans la page de résultat de la requête GET /accounts
• Cet appel permet de récupérer le solde d’un compte de paiements du PSU (usager d’un service de paiement) pour lequel l’AISP (prestataire de service de paiement) est connecté
• Ce service fait suite à la restitution de la liste des comptes d’un client : un identifiant de ressource (« accountResourceId ») correspondant à un compte doit être fourni pour en obtenir son solde
• Seul le type de solde Comptable (« CLBD » dans la norme STET) sera retourné pour le compte passé en paramètre

Les accès à cette méthode sont limités à 4 accès batch maximum par jour par TPP, pour un client et pour un IBAN donné.

En revanche, lorsque c’est notre client connecté qui interroge directement ses comptes, le nombre d’accès n’est pas limité.

Exemple

Un exemple de requête est fourni dans la rubrique « Comment tester l’API ? » > « Assemblage Sandbox ».

Les jeux de données de tests sont décrits dans la rubrique « Comment tester l’API ? » > « Tester nos persona ».

Voir aussi la spécification de place STET 

Test d’acceptance

Ces cas de tests ont pour objectif de vous permettre d’effectuer un minimum de tests afin de prendre en main cette API et d’y accéder depuis votre application. Ils devront être validés avant tout déploiement applicatif en production.

Obtenir les transactions

Ce service permet de lister les transactions d’un compte de paiments éligible DSP2 du client (ainsi que le détail s’il est disponible) qui a donné son consentement au TPP pour pouvoir y accéder.

Le type de compte est soit un compte de dépôt pour les particuliers, soit un compte courant pour les professionnels et les personnes morales.

Prérequis

Pour récupérer les transactions d’un compte de dépôt ou d’un compte courant :

• L’IBAN du compte doit nous avoir été transmis dans la liste « transactions » de la méthode PUT /consents et ne doit pas avoir été révoqué depuis (= pas de requête PUT /consents SANS IBAN)
• L’identifiant de ressource permettant d’interroger cette méthode pour ce compte de paiement, est récupéré via le résultat de la requête GET /accounts, rubrique « resourceId » pour le compte correspondant à cet IBAN (lui-même inclus dans « accountId » : {« iban »: »<IBAN du compte> »})
• L’URI pour l’accès à cette méthode est donnée via la rubrique « _links » : {« transactions »: {« href »: …}} en résultat de la requête GET /accounts pour le « resourceId » du compte.

Requête

GET /account/{accoundResourceId}/transactions

GET /accounts/{accountResourceId}/transactions/{transactionResourceId}/details (à appeler pour chaque détail de transaction à remonter)

Voir aussi la spécification de place STET 

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

Paramètres obligatoires :

• accountResourceId => compte éligible DSP2 pour lequel on veut consulter les opérations
• transactionResourceId => identification de la ressource à récupérer

Paramètres facultatifs supportés:

• dateFrom => date limite de début pour les transactions recherchées. Les transactions ayant une date d’imputation égale au paramètre dateFrom sont restituées dans le résultat
• dateTo => date limite de fin pour les transactions recherchées. Les transactions ayant une date d’imputation égale au paramètre dateTo ne sont pas restituées dans le résultat.
• PSU-IP-ADDRESS => à alimenter si le client est connecté

Paramètres facultatifs NON supportés :

• dateType
• entryReferenceFrom
• entryReferenceTo

Le format pour les données dateFrom et dateTo est l’ISO 8601 avec les trois expressions régulières autorisées qui sont :

• YYYY-MM-DDTHH:MM:SS.SSS ou YYYY-MM-DDTHH:MM:SS.SSSZ
• YYYY-MM-DDTHH:MM:SS.SSS+HHMM
• YYYY-MM-DDTHH:MM:SS.SSS+HH:MM

Résultat retourné

Cet appel permet de récupérer la liste des opérations pour le compte passé en paramètre.

La date des transactions obtenue est inférieure ou égale à 90 jours par rapport à la date du jour.

Des liens « self » seront également présents pour :

• avoir accès aux détails de la transaction (si disponibles)
• revenir à la page obtenue juste après exécution de la requête.

Les accès à cette méthode sont limités à 4 accès batch maximum par jour, pour un client et pour un compte donné. En revanche, lorsque c’est notre client connecté qui interroge directement ses comptes, le nombre d’accès n’est pas limité.

La donnée optionnelle STET entryReference a été ajoutée pour toutes les opérations sachant qu’elle est :

• unique durant le cycle de vie de la transaction à débit différé (*)
• identique avant et après imputation pour les opérations suivantes qui passeront du statut « OTHR » à « BOOK » :
  • carte à débit différé
  • virement différé (SEPA SCT Core)
  • prélèvement 

(*) NB 1 : cette donnée sera identique pour toutes les échéances d’un même virement permanent

NB 2 : les autres typologies d’opérations (par exemple les opérations de carte à débit immédiat, les virements immédiats, etc…) n’auront cette donnée qu’au statut « BOOK » sauf celles refusées

Les longueurs et formats sont différents suivant le type d’opérations :

La donnée optionnelle STET Bank Transaction Code (BTC) a été rajoutée seulement pour les segments clients PRO et ENT (= abonnés CE Net ou ayant souscrit une offre équivalente), par exemple pour le cas d’un virement SEPA SCT :

« bankTransactionCode »: {

« domain »: « PMNT »,

« family »: « RCDT »,

« subFamily »: « ESCT »,

« code »: « 05 »,

« issuer »: « SI MYSYS – Caisse d’Epargne »

}

Exemple

Un exemple de requête est fourni dans la rubrique « Comment tester l’API ? » > « Assemblage Sandbox ».

Les jeux de données de tests sont décrits dans la rubrique « Comment tester l’API ? » > « Tester nos persona ».

Voir aussi la spécification de place STET

Tests d’acceptance

Ces cas de tests ont pour objectif de vous permettre d’effectuer un minimum de tests afin de prendre en main cette API et d’y accéder depuis votre application.

Ils devront être validés avant tout déploiement applicatif en production.

Obtenir l'identité du client

Cas d’usage

Ce service permet de récupérer l’identité d’un client qui a donné son consentement au TPP pour pouvoir y accéder.

Prérequis

Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité et d’avoir récupéré le jeton d’accès OAuth2 (voir la rubrique « Cas d'usage » > « Récupérer votre jeton » ).

Pour récupérer l’identité d’un PSU :

• L’autorisation de transmettre au TPP ces informations d’identité doit nous avoir été transmis via la valorisation à true de l’attribut « psuIdentity » de la méthode PUT /consents et ne doit pas avoir été révoqué depuis (c’est à dire pas d’annule et remplace via PUT /consents avec un attribut « psuIdentity » valorisé à false)
• L’URI pour l’accès à cette méthode est donnée via la rubrique « _links« : {« endUserIdentity »: {« href »: …}} en résultat de la requête GET /accounts.

Requête

GET /end-user-identity

Voir aussi la spécification de place STET 

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

Paramètres obligatoires : PSU-IP-ADDRESS => à alimenter si le PSU est connecté.

Résultat retourné

Cet appel permet de récupérer l’identité du client final.

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

Vos accès à cette méthode sont limités à 4 accès batch maximum par jour calendaire, pour un client. En revanche, lorsque c’est le client connecté qui interroge directement ses comptes à vue, le nombre d’accès n’est pas limité.

Exemple

Requête

GET /stet/psd2/v1.4.2/end-user-identity

Un exemple plus complet de requête est fourni dans la rubrique « Comment tester l’API ? » > « Assemblage sandbox ».

Voir aussi la spécification de place STET

Obtenir le découvert autorisé

Ce service permet de récuperer le découvert autorisé d’un compte de paiement d’un client qui a donné son consentement au TPP pour pouvoir y accéder.

Ce type de compte est soit un compte de dépôt pour les particuliers, soit un compte courant pour les professionnels et les personnes morales.

Prérequis

Ce service fait suite à la restitution de la liste des comptes d’un client : un identifiant de ressource correspondant à un compte doit être fourni pour obtenir le découvert autorisé.

Pour récupérer le découvert autorisé d’un compte :

• L’IBAN du compte doit nous avoir été transmis dans la liste « balances » de la méthode PUT /consents et ne doit pas avoir été révoqué depuis (=> pas d’annule et remplace via PUT /consents sans cet IBAN dans la liste « overdrafts »)
• L’ »accountResourceId » permettant d’interroger cette méthode pour ce compte courant, est récupéré via le résultat de la requête GET /accounts dans la rubrique « resourceId » pour le compte correspondant à cet IBAN, c’est-à-dire tel que « accountId »: {« iban »: » » }
• L’URI pour l’accès à cette méthode est donnée via la rubrique « _links »: {« overdrafts »: »{« href »: …}} en résultat de la requête GET /accounts pour le « resourceId » du compte

Requête

Requête « GET /accounts/{accountResourceId}/overdrafts »

Voir aussi la spécification de place STET 

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

Paramètre obligatoire : accountResourceId (compte pour lequel le découvert doit être retourné).

Cette donnée correspond à la rubrique « resourceId » obtenue dans la page de résultat de la requête GET /accounts.

Les accès à cette méthode sont limités à 4 accès batch maximum / jour / TPP / IBAN / ASPSP / PSU donnés.

En revanche, lorsque c’est notre client connecté qui interroge directement ses comptes via un TPP, le nombre d’accès n’est pas limité.

Exemple

Un exemple de requête est fourni dans la rubrique « Comment tester l’API ? » > « Assemblage Sandbox ».

Les jeux de données de tests sont décrits dans la rubrique « Comment tester l’API ? » > « Tester nos persona ».

Voir aussi la spécification de place STET 

Rafraîchir 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 TPP » (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 réglementaire (max 180 jours actuellement)
• 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. Le TPP demande 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 QWAC du TPP

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 forte du PSU (< 180 jours actuellement)

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

7. Vous stockez le nouveau 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 « Comment tester l’API ? » > « Assemblage Sandbox ».

Assemblage sandbox

Introduction

La sandbox BPCE API peut être accédée directement via votre application : c’est le mode assemblage décrit ci-après.

Les données utilisées sont fictives (voir la rubrique « Comment tester l’API ? » > « Tester nos persona »). Elles permettront de choisir des profils spécifiques de façon à mieux cibler vos tests.

Prérequis

Vous devez déclarer votre APP via l’API Enregistrement DSP2 (en choisissant le point d’entrée « sandbox ») et nous transmettre :

• votre identifiant fourni par votre autorité compétente (Organization Identifier = OID)
• la clé publique de votre certificat QSEALC (de production dédié aux tests)
• votre URI de redirection (redirect_uri) qui sera appelée par l’ASPSP :
  • 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 ci-dessous est interrompue (par exemple : timeout sur les écrans)

Rappel : vous devez être accrédité pour le rôle « AISP ».

Enchaînement des étapes pour tester l’accès à l’API AISP depuis votre APP
 

1ère étape : demande de jeton d’accès

Ceci est nécessaire afin d’obtenir un jeton d’accès à toutes fins de consommer les ressources de l’API, et permet de déclencher la redirection du PSU chez l’ASPSP.

La description de la fonctionnalité est décrite dans la rubrique « Cas d'usage » > « Récupérer votre jeton » .

NB : Le PSU peut domicilier ses comptes dans plusieurs banques du Groupe BPCE. Il vous faudra un jeton différent pour accéder à chacune de ces banques –> cet appel est donc à répéter pour chacun des établissements concernés.

Notre point d’entrée dépend du code établissement : www.<cdetab>.sandbox.api.89C3.com, et pour l’assemblage sandbox, le seul <cdetab> est fixé à 17515 (Caisse d’Epargne Ile de France).

Exemple de requête en assemblage sandbox :

GET https://www.17515.sandbox.api.89C3.com/stet/psd2/oauth/authorize

Headers :

Content-Type: application/x-www-form-urlencoded; charset=utf-8

Params:

response_type:code

client_id:PSDFR-ACPR-13807

redirect_uri:https://myAPP.fr/Home/OAuth2Callback

scope:aisp

Remarque sur l’alimentation des champs :
 

• client_id: identifiant fourni par votre autorité nationale compétente (PSDXX-YYYY-ZZZZZ)
• redirect_uri: URL de redirection prédéclarée dans votre application consommatrice ET à communiquer à l’ASPSP pour toute une demande d’assemblage ou de Go Live

2ème étape : redirection vers les écrans d’authentification forte (AF/SCA)

Une fois redirigé vers l’ASPSP, celui-ci va afficher des écrans d’identification et d’authentification au PSU.

La cinématique nominale des enchaînements de ces écrans est résumée par le schéma ci-dessous :

Image

1. Le PSU est redirigé vers un écran d’identification proposé par ASPSP.

L’identifiant banque à distance du PSU est à saisir :

Image

NB : si le PSU est un professionnel ou une entreprise, il y aura un numéro d’usager à saisir en sus de l’identifiant banque à distance.

2. Le PSU se voit afficher alors un écran d’authentification forte proposé par l’ASPSP pour valider son identité.

La cinématique dépend aussi de la méthode d’authentification forte (AF/SCA) mise à disposition par l’ASPSP (exemple d’un OTP par SMS, voir exemple ci-dessous) :

Image

ou pour la sandbox

Image

NB : Dans certains cas, une notification peut être envoyée vers le PSU afin qu’il active son moyen d’AF/SCA sur son smartphone pour terminer cette étape :

Image

3ème étape : récupération du jeton d’accès / access_token

Cet appel permet à l’AISP de récupérer le jeton d’accès pour pouvoir accéder aux données.

La description de la fonctionnalité est décrite dans la rubrique « Cas d'usage » > « Récupérez votre jeton ».

Le certificat QWAC est à fournir dans cette requête POST /stet/psd2/oauth/token pour établir l’authentification mutuelle avec l’ASPSP. Le certificat doit correspondre à celui-ci que le PSP a fourni:

• lors de l’étape goAssemblage (resp. goLive en production) si le TPP a été enregistré par la procédure via le portail BPCE API
• ou via l’API Enregistrement DSP2 si le TPP (auto-enrôlement automatisé)

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:PSDFR-ACPR-13807

grant_type:authorization_code

code:NnZx1hqHY2CLkCFjiTwhJeflgFedCBa

redirect_uri:https://myAPP.fr/Home/OAuth2Callback

Remarques sur l’alimentation des champs :

• client_id : numéro donné par votre autorité compétente lors de votre demande d’agrément (PSDXX-YYYY-ZZZZZ)
• code : récupéré dans l’url de callback
• redirect_uri : il faut que cette « redirect_uri » soit identique à celle envoyée dans la requête GET /authorize !!!
• le certificat eiDAS QWAC doit être envoyé avec cette requête

Réponse :

4ème étape : consommation des méthodes de l’API

1) Obtenir la liste des comptes à vue d’un PSU

Une fois le jeton d’accès récupéré après l’authentification forte du PSU, cet appel vous permet de lister les comptes du PSU connecté lors de la première connexion.

La description de la fonctionnalité est décrite dans le cas d’usage « Obtenir la liste des comptes » , notamment sur la pemière utilisation de cette méthode avant un PUT /consents.

La séquence est :

1. GET /accounts pour récupérer les comptes sans les soldes et sans les links vers les soldes et transactions
2. affichage des comptes au client par le TPP pour récupérer son consentement
3. PUT /consents pour transmettre le consentement sur les comptes
4. GET /accounts pour récupérer les comptes consentis et les links vers le solde (si donnée consentie) et/ou vers les transactions (si données consenties)

Exemple de requête en assemblage sandbox SANS PUT /Consent au préalable:

GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts

Header :

Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-Request-ID: id-1234567890111121 1 

Signature: keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_‎<empreinte sha256>\ », algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QiMViAmthebEst=\ »

Psu-IP-Address:192.168.0.1

Pas de corps de requête

Remarques sur l’alimentation des champs :

• Authorization : Bearer < access_token précédemment récupéré>
• X-Request-ID : <en-tête de corrélation de la requête émise>
• Signature : <signature de la requête émise>
• Psu-Ip-Address => permet de différencier les appels batch et les appels avec le PSU connecté : ce champ est à alimenter pour un PSU connecté

Réponse : 200 (=> OK)

Header :

X-request-id: id-1234567890111121 1

Content-Type: application/hal+json;charset=UTF-8

Body :

{

Exemple de requête en assemblage sandbox AVEC la méthode PUT /Consent au préalable:

GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts

Header :

Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-Request-ID: iid-1234567890111121 2

Signature: keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_‎<empreinte sha256>\ », algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxinDocH1ne=\ »

Psu-IP-Address:192.168.0.1

Pas de corps de requête

Remarques sur l’alimentation des champs :

• Authorization : Bearer < access_token précédemment récupéré>
• X-Request-ID : <en-tête de corrélation de la requête émise>
• Signature : <signature de la requête émise>
• Psu-Ip-Address => permet de différencier les appels batch et les appels avec le PSU connecté : ce champ est à alimenter pour un PSU connecté

Réponse : 200 (=> OK)

Header :

X-request-id: id-1234567890111121 2

Content-Type: application/hal+json;charset=UTF-8

Body :

{

2) Transmettre la liste des comptes consentis par le PSU
 

Cet appel vous permet de transmettre à l’ASPSP la liste des comptes consentis par le PSU.

La description de la fonctionnalité est décrite dans le cas d’usage « Transmettre la liste des comptes ».

Exemple de requête en assemblage sandbox :

PUT https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.4.2/consents
 

Headers :

Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-request-id: id-1234567890111121 3

Signature: keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_‎<empreinte sha256>\ »,algorithm=\ »rsa-sha256\ »,headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ »,signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4

Psu-IP-Address:192.168.0.1

Body :
{

}

Réponse : 201 (=> created)

Headers :

X-request-id: id-1234567890111121 3

Pas de body 

3) Obtenir le solde

Cet appel vous permet d’obtenir le solde d’un compte consenti.

La description de la fonctionnalité est décrite dans le cas d’usage « Obtenir les soldes d’un compte » , et cette information n’est remontée que si un consentement PSU a été reçu au préalable par l’ASPSP via la méthode PUT /consents.

Exemple de requête en assemblage sandbox avec un {accountResourceId} = numéro de compte ciblé :

GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.6.2/accounts/175159000004003580740/balances

Headers :

Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-request-id: id-1234567890111121 4

Signature: keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_‎<empreinte sha256>\« ,algorithm=\ »rsa-sha256\ »,headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ »,signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4x

Réponse :

200 OK

Headers :

X-request-id: id-1234567890111121 4

Content-Type: application/hal+json;charset=UTF-8

Body :

{

« balances »: [

{

« balanceType »: « CLBD »,

« name »: « Solde comptable au 01/07/2022 »,

« balanceAmount »: {

« amount »: « -150.00 »,

« currency »: « EUR »

}

}

],

« _links »: {

« self »: {

« templated »: false,

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/balances »

},

« transactions »: {

« templated »: false,

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/transactions »

},

« overdrafts »: {

« templated »: false,

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/overdrafts »

},

},

« parent-list »: {

« templated »: false,

« href »: « /stet/psd2/v1.6.2/accounts »

}

}

}

4) Obtenir les transactions

Cet appel vous permet d’obtenir les transactions d’un compte consenti.

La description de la fonctionnalité est décrite dans le cas d’usage « Obtenez les transactions » , et ces informations ne sont remontées que si un consentement PSU a été reçu au préalable par l’ASPSP via la méthode PUT /consents.

Exemple de requête en assemblage sandbox avec un {accountResourceId} = numéro de compte ciblé :

GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.6.2/accounts/175159000004003580740/transactions

Headers :

Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-request-id: id-1234567890111121 5

Signature: keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_‎<empreinte sha256>\« ,algorithm=\ »rsa-sha256\ »,headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ »,signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1T0tOtuTuT1ti=\ »

Psu-IP-Address:192.168.0.1

Pas de body

Réponse : 200 (=> OK)

Headers :

X-request-id: id-1234567890111121 5

Content-Type: application/hal+json;charset=UTF-8

Body :

{

« transactions »: [

{

« entryReference »: « 382040554102518000713473520220722 »,

« transactionAmount »: {

« amount »: 8.12,

« currency »: « EUR »

},

« creditDebitIndicator »: « DBIT »,

« status »: « BOOK »,

« bookingDate »: « 2022-07-23T00:00:00+0200 »,

« bankTransactionCode »: {

« domain »: « PMNT »,

« family »: « RDDT »,

« subFamily »: « OTHR »,

« code »: « 06 »,

« issuer »: « SI MYSYS – Caisse d’Epargne »

},

« remittanceInformation »: {

« unstructured »: [

« VIR SEPA BP RIVES PARIS »

]

},

« _links »: {

« details »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/transactions/RUNIU0VQQTgwMDA3MTM0NzM1IERVMjIwNzIwMjJUXzIzMDcyMDIyXzIwMjItMDctMjMtMDEuMTguNTIuODE4ODMxXzQ2MTAw/details »,

« templated »: false

}

}

},

{

« entryReference »: « 382040554102512022-07-12-02.42.40.510668 »,

« transactionAmount »: {

« amount »: 11.4,

« currency »: « EUR »

},

« creditDebitIndicator »: « DBIT »,

« status »: « BOOK »,

« bookingDate »: « 2022-07-12T00:00:00+0200 »,

« bankTransactionCode »: {

« domain »: « ACMT »,

« family »: « MDOP »,

« subFamily »: « COMM »,

« code »: « 62 »,

« issuer »: « SI MYSYS – Caisse d’Epargne »

},

« remittanceInformation »: {

« unstructured »: [

« * COT FORFAIT FSE + »

]

},

« _links »: {

« details »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/transactions/bnVsbF8xMjA3MjAyMl8yMDIyLTA3LTEyLTAyLjQyLjQwLjUxMDY2OF8zMDYwMA/details »,

« templated »: false

}

}

},

{

« entryReference »: « 382040554102512022-07-06-11.22.06.175250 »,

« transactionAmount »: {

« amount »: 8.25,

« currency »: « EUR »

},

« creditDebitIndicator »: « DBIT »,

« status »: « BOOK »,

« bookingDate »: « 2022-07-06T00:00:00+0200 »,

« bankTransactionCode »: {

« domain »: « PMNT »,

« family »: « ICDT »,

« subFamily »: « DMCT »,

« code »: « 06 »,

« issuer »: « SI MYSYS – Caisse d’Epargne »

},

« remittanceInformation »: {

« unstructured »: [

« VIREMENT VERS BP RIVES PARIS »

]

},

« _links »: {

« details »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/transactions/U0VQQSAyMjE4Nzg1QlAwMDAwMDAyOTk5OThfMDYwNzIwMjJfMjAyMi0wNy0wNi0xMS4yMi4wNi4xNzUyNTBfbnVsbA/details »,

« templated »: false

}

}

},

{

« entryReference »: « 382040554102512216685I10000004 »,

« transactionAmount »: {

« amount »: 11.33,

« currency »: « EUR »

},

« creditDebitIndicator »: « DBIT »,

« status »: « BOOK »,

« bookingDate »: « 2022-06-15T00:00:00+0200 »,

« bankTransactionCode »: {

« domain »: « PMNT »,

« family »: « IRCT »,

« subFamily »: « ESCT »,

« code »: « C1 »,

« issuer »: « SI MYSYS – Caisse d’Epargne »

},

« remittanceInformation »: {

« unstructured »: [

« VIR INST DES C17 »

]

},

« _links »: {

« details »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/transactions/MjIxNjY4NUkxMDAwMDAwNDIwMjIwNjE1ICAgSVAwXzE1MDYyMDIyXzIwMjItMDYtMTUtMTEuMzMuNTcuNTI5ODQzX251bGw/details »,

« templated »: false

}

}

}

],

« _links »: {

« self »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/transactions »,

« templated »: true

},

« balances »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/balances »,

« templated »: false

},

« overdrafts »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/overdrafts »,

« templated »: false

},

« parent-list »: {

« href »: « /stet/psd2/v1.6.2/accounts »,

« templated »: false

}

}

}

5) Obtenir l’identité du client

Cet appel vous permet d’obtenir l’identité du PSU connecté (qui n’est pas forcément le client possédant le compte).

La description de la fonctionnalité est décrite dans le cas d’usage « Obtenir l’identité du client » , et cette information n’est remontée que si un consentement PSU a été reçu au préalable par l’ASPSP via la méthode PUT /consents.

Exemple de requête en assemblage sandbox :

GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.6.2/end-user-identity

6) Rafraîchir le jeton d’accès

Cet appel vous permet d’obtenir le découvert autorisé du PSU.

La description de la fonctionnalité est décrite dans le cas d’usage « Obtenir le découvert » , et cette information n’est remontée que si un consentement PSU a été reçu au préalable par l’ASPSP via la méthode PUT /consents.

Exemple de requête en assemblage sandbox :

GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.6.2/accounts/175159000004003580740/overdrafts

Headers :

Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-request-id: id-1234567890111121 7

Signature: keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_‎<empreinte sha256>\« ,algorithm=\ »rsa-sha256\ »,headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ »,signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1T0tOtuTuT1ti=\ »

Psu-IP-Address:192.168.0.1

Pas de body

Réponse : 200 (=> OK)

Headers :

X-request-id: id-1234567890111121 7

Content-Type: application/hal+json;charset=UTF-8

Body :

{

« overdrafts »: {

« allowedAmount »: {

« amount »: 0,

« currency »: « EUR »

}

},

« _links »: {

« self »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/overdrafts »,

« templated »: false

},

« balances »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/balances »,

« templated »: false

},

« transactions »: {

« href »: « /stet/psd2/v1.6.2/accounts/175159000004003580740/transactions »,

« templated »: true

},

« parent-list »: {

« href »: « /stet/psd2/v1.6.2/accounts »,

« templated »: false

}

}

}

7) Rafraîchir le jeton d’accès

Cet appel vous permet de rafraichir le jeton d’accès avec le refresh-token.

La description de la fonctionnalité est décrite dans la rubrique « Cas d'usage » > « Rafraîchir votre jeton ». 

Exemple de requête en assemblage 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: PSDFR-ACPR-13807

grant_type: refresh_token

refresh_token: KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAbCdEf

Réponse : 

{

}

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

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

ATTENTION : NOUVEAUX IDENTIFIANTS  

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 :

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 Groupe BPCE API Store 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*.

(*) NB : l’article 30 (4) des RTS précise que des changements significatifs de l’API peuvent intervenir sans délai. Nous appliquons cette clause dans les cas suivants :

• problème bloquant impactant de façon généralisée au moins l’un des segments de clients majeur (particuliers, professionnels, entreprises),
• problème de sécurité,
• évolutions demandées par les autorités nationales compétentes pour répondre à la trajectoire réglementaire.

Retrouvez ci-dessous notre roadmap prévisionnelle.

Limitations fonctionnelles

Limitations de cette API DSP2 

• Ne s’applique qu’aux comptes de paiements (le critère déterminant réside dans la faculté d’exécuter des opérations de paiement quotidiennes à partir d’un tel compte géré par le système d’information central « backend », source des informations remontées par les API), en euros et éligibles (compte de paiements actif – non bloqué ni sous séquestre-, et accessible en ligne, cf. texte de la Directive DSP2)
   
• N’utilise que le mode d’authentification par redirection (Authentification Forte du client demandée et gérée via la banque teneur de compte du client utilisateur du service de paiement)
  NB : le TPP n’a pas la possibilité de fournir à l’ASPSP les données de sécurité personnalisées du client à des fins d’authentification, et donc, seuls les écrans de redirection et d’authentification forte (SCA) de l’ASPSP doivent être utilisés (l’encapsulage de ces écrans par le TPP est interdit au regard des articles PSD2 #97.5 et RTS #31)
   
• N’implémente que le mode de consentement « mixte AISP » via la méthode PUT /consents qui devient obligatoire :
  • tous les comptes à vue sont remontés (y compris les nouveaux)
  • le détail des soldes et des transactions exécutées n’est accessible que pour les comptes de paiements dont le consentement a été transmis par le TPP
     
• Ne fixe pas de limite d’accès (rate limit) lorsque c’est le PSU connecté qui interroge ses comptes de paiements (PSU-IP-ADDRESS fourni), sinon limité à 4 accès à l’initiative du TPP (cf. texte de la Directive DSP2) :
  • par jour calendaire (00h00:00:000 – 23h59:59:999)
  • par TPP OID
  • par ASPSP / point d’accès
  • par PSU ID
  • par IBAN
  • par méthode API AIS (/!\ méthode /transactions avec ou sans dateFrom / dateTo = considérée une seule et même méthode)
     
• Ne permet l’accès au compte que via l’IBAN du compte de paiement
   
• Seules les méthodes GET /accounts, PUT /consents, GET /balances, GET /transactions, GET /details, GET /overdrafts, GET /end-user-identity sont disponibles :
  • le mode « aisp extended_transaction_history » n’est pas supporté : la profondeur d’historique des transactions est à l’identique de celle de la banque en ligne internet fixe, soit un maximum de 62 jours pour les PRO (pas de pagination gérée par l’API), et 90 jours pour les ENT (limitation à 500 comptes, pas de pagination gérée par l’API)
  • ne permet pas de récupérer la liste des bénéficiaires de confiance d’un client (cette notion n’existe pas pour les établissements listés ci-dessous)
  • ne permet pas de récupérer la liste des propriétaires d’un compte via GET /owners (fonctionnalité non supportée)
     
• Pas de gestion des données optionnelles « dateType » et « entryReference » (via les paramètres « entryReferenceFrom » / « entryReferenceTo »)

Limitations liées aux segments de clientèle 

Sont couverts par l’API les segments clients suivants :

• Client « particulier » (y compris compte joint et mineur rattaché) ayant un abonnement à la banque en ligne « DEI PART » ou « DEI PRO » et un compte commençant par 04
   
  NB 1 : le particulier (PART) est une personne physique catégorisée comme « majeur capable ». Le PART peut aussi avoir des activités dans le cadre d’une entreprise individuelle (EI) = une entreprise dirigée par une seule personne, et qui n’a pas le statut de « persone morale », bien qu’elle soit inscrite au répertoire des métiers ou au Registre du Commerce et des Sociétés (RCS, exemples : artisan ou profession libérale). Dans ce cas, l’EI est considéré comme un PART
  
  NB 2 : est non compris à ce jour le tuteur de personne protégée/sous tutelle ou curatelle utilisant la solution Web Protexion 
   
• Client « entrepreneur individuel » (EI) et « petit professionnel » ayant un abonnement à la banque en ligne « DEI PRO » et un compte commençant par 04 ou 08
  
  NB 3 : les catégories « entreprise » (ENT) et « association » (ASSOC) couvrent les personnes morales. 
   
• Client « gros professionnel », « entreprise » et « association » ayant un accès direct à la banque en ligne « CE Net » (ayant un abonnement « CE Net Compte » et un compte commençant par 08 autorisant les virement et prélèvements électroniques)
  
  NB 4 : les catégories « professionnel » (PRO), « entreprise » (ENT) et « association » (ASSOC) couvrent les personnes morales.  
  
   

Limitations liées aux moyens d’authentification forte

• Il est de la responsabilité de l’ASPSP d’équiper ses clients avec un ou des moyens d’authentification forte :
  • PART :       Accès aux comptes PART et Opération sensible / Dynamic linking (DL) :  (Sécur’Pass) ou (lecteur CAP) ou (Mot de Passe + OTP SMS)
  • PRO/ENT : Accès aux comptes PART et Opération sensible / Dynamic linking (DL) : (certificat matériel) ou (Sécur’Pass) ou (lecteur CAP) ou (Mot de Passe + OTP SMS)
    
    NB 5 : le certificat matériel n’est pas proposé aux client sur mobile/smartphone

Accès aux données de production

Conformément à la réglementation, les modes de test Try-it et Assemblage n’utilisent que des données fictives. Ces données de tests sont décrites dans la rubrique « Comment tester l’API ? ».

Pour accéder aux données de production, l’utilisation de l’API Enregistrement DSP2 est un prérequis.

NB : La plage hebdomadaire du lundi matin de minuit à 06h00 est utilisée pour la maintenance des infrastructures des systèmes d’information (tous composants, y compris le système central/backend, les passerelles, etc…) et peut engendrer des requêtes API en erreur ou des indisponibilités le temps des interventions (de même pour des traitements bancaires programmés en début et fin de journée/mois/trimestre/année).

Le code établissement (voir ci-dessous) permettra d’adresser le bon backend via le point d’accès www.<cdetab>.oba-bad-me-live.api.89c3.com (nouvelle url à prendre en compte dès à présent)
(ou www.<cdetab>.live.api.caisse-epargne.fr aligné sur le nom de domaine de l’accès direct www.caisse-epargne.fr)
(Pour rappel, l’url 89C3 existante www.<codetab>.live.api.89C3.com ne sera plus disponible à partir du 28/09/2025)

Une fois choisi, ce point d’accès doit être conservé pour toutes les requêtes sous-jacentes.

Eligibilité

Les ressources de l’API “Agrégation de comptes” ne peuvent être consommées que par des PSP ayant le rôle d’agrégateur (AISP). 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 Enregistrement DSP2 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 Enregistrement DSP2) pour la sandbox
• un autre jeu de certificats QWAC (pour l’authentification mutuelle TLS) et QSEALC (à charger sur notre passerelle via l’API Enregistrement DSP2) 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 élements de la nouvelle autorité de certification sont bien chargés sur nos infrastuctures. 

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

Principaux changements effectués depuis la première version publiée