Banque Populaire – Information sur compte – (Norme STET v1.4.2)
Accédez aux données bancaires autorisées par le client
Agréger les données
Un client multi bancarisé souhaite accéder à l’ensemble de ses données afin d’en avoir une vision consolidée.
Via cette API « information sur compte » mise à disposition par les teneurs de comptes, vous pouvez demander en temps réel l’accès à l’une et/ou l’autre des données que le client a autorisé SANS lui demander ses identifiants de connexion en ligne.
Vous pouvez récupérer les comptes à vue de ce client dans la banque où ils sont localisés. Pour ces comptes à vue, en fonction des consentements du client que vous aurez recueillis et que vous nous aurez transmis, vous pouvez récupérer leurs soldes, leurs transactions, les cartes à débit différés qui s’y rattachent, les encours et les facturettes de ces cartes à débit différé.
Vous pouvez accéder à cette API en batch afin de préparer la restitution au client sur votre application (au plus 4 fois par jour). A la demande du client connecté sur son application, vous pouvez rafraîchir ces données (sans limitation).
Cette API ne peut être consommée que si vous avez obtenu le rôle de prestataire de Services d’Information sur les Comptes (« TPP AISP »), ce prérequis étant décrit dans voir la rubrique « Éligibilité« .
Le processus global est le suivant :
Le client souhaite utiliser vos services afin de consolider des informations d’un ou plusieurs comptes de paiements détenus auprès de banques, dont l’une d’entre-elles est la banque du client. Il vous indique donc cette banque à travers vos interfaces.
Lors de ce premier échange, vous allez faire une demande de jeton d’autorisation (et un jeton de rafraichissement). Le principe de base est, qu’en tant que TPP AISP, vous devez obtenir ces jetons AVANT de consommer des ressources de l’API. Ce jeton est généré par le teneur de compte (ASPSP) APRES avoir identifié et authentifié le client.
En tant que teneur de compte :
- nous allons vérifier vos certificats et agréments
- et via le jeu de la redirection, nous allons identifier et authentifier fortement le client afin de pouvoir générer le jeton d’accès
Si l’autorisation est accordée par le client, vous pourrez alors récupérer les jetons OAUTH2 via des échanges sécurisés avec la plateforme BPCE API (voir la rubrique « Vue d’ensemble » > « Récupérer votre jeton« ).
En présentant ce jeton d’autorisation, vous pourrez alors consommer les ressources de l’API « information sur compte » afin de :
- demander la liste des comptes éligibles
- nous transmettre le consentement client
- accéder de manière sécurisée aux données dont l’accès a été autorisé (voir la rubrique « Vue d’ensemble » > « Comment consommer l’API ?« ).
Au bout du délai réglementaire de 180 jours, ce processus devra être reconduit (voir la rubrique « Vue d’ensemble » > « Rafraîchir votre jeton« ).
NB : le gestionnaire de compte ASPSP a la possibilité de vous refuser l’accès pour différents motifs justifiés (API non conforme, compte bloqué entre-temps, etc.).
Consommer l'API
La description des services proposés ci-après n’est que purement fonctionnelle. Les aspects techniques sont répertoriés dans les sections « 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), l’assistant virtuel ou le glossaire.
Introduction – consentement mixte AISP vs consentement full AISP
La norme STET propose deux modes de gestion du consentement : le consentement full AISP et le consentement mixte AISP. Seul le mode de consentement mixte AISP a été développé.
La cinématique ci-après décrit son implémentation et en particulier l’utilisation de la méthode PUT /consents qui vous permet de transmettre les comptes consentis par le client.
Elle résume comment s’enchaînent les appels aux différentes méthodes de l’API AISP, depuis la récupération du jeton, jusqu’à la récupération des comptes à vue et des cartes à débits différés ainsi que leurs soldes / transactions et leurs encours / facturettes respectivement, ainsi que la récupération de l’identité du client.
Prérequis
En tant que TPP, vous devez être accrédité par l’autorité de contrôle prudentiel et de résolution (ACPR) pour le rôle d’agrégateur de compte (« AISP »).
Pour accéder aux services de l’API d’information sur compte, vous devez récupérer un jeton d’accès OAUTH2 délivré par l’établissement bancaire du client en l’interrogeant avec vos credentials. Ce jeton est valable 180 jours.
Vous et l’établissement bancaire du client, vous devez vous authentifier mutuellement par échange des certificats Eidas QWAC.
Vous présentez ensuite votre jeton d’accès OAUTH2 pour consommer les services de l’API d’information sur compte.
Agréger les données
Cas d’utilisation de l’API d’information sur compte :
L’AISP questionne le client (PSU) pour connaître le(s) établissement(s) bancaire(s) à partir du(des)quel(s) il souhaite consulter ses comptes
La méthode d’authentification supportée par l’établissement bancaire est le mode REDIRECT :
Autorisation d’accès en tant qu’AISP qui vous est donnée par le client connecté – récupération du jeton d’accès initial valable 180 jours et du refresh token
1. Le client est redirigé vers un écran d’identification proposé par son établissement bancaire et dans lequel il saisira son identifiant de banque à distance. Si l’AISP fournit l’identifiant de banque à distance du client dans sa requête, l’étape suivante est directement déclenchée.
2. Le client est redirigé vers un écran d’authentification forte proposé par son établissement bancaire pour valider son identité. La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du client par l’établissement bancaire (SMS OTP, secur’pass, etc.). Elle dépend aussi de l’équipement du client sur lequel tourne l’APP de l’AISP utilisée par le client (PC ou mobile/tablette).
3. Le client est redirigé vers l’APP de l’AISP. L’AISP fournit lors de sa demande de récupération de jeton une URL call back : elle sera appelée par l’établissement bancaire.
Premier accès pour récupérer la liste des comptes à vue du client
Vous récupérez la liste des comptes à vue du client via un premier accès à la méthode GET /accounts en fournissant votre jeton d’accès pour ce client (cf. cas d’usage « Lister les comptes« ).
Vous n’avez pas accès aux informations suivantes :
- les soldes des comptes à vue
- les URI vers la méthode GET /accounts/balances
- les URI vers la méthode GET /accounts/transactions
- les URI vers la méthode GET /end-user-identity
- l’URI vers la méthode GET /trustedBeneficiaries
=> ce service n’est pas disponible
Tant que vous n’aurez pas transmis les comptes consentis par le client via la méthode PUT /consents :
- vous pourrez toujours récupérer la liste des comptes à vue du client via la méthode GET /accounts, mais vous n’aurez pas plus d’informations qu’au premier accès avec cette méthode
- si vous essayez d’utiliser la méthode GET /accounts/transactions, la requête sera rejetée
- si vous essayez d’utiliser la méthode GET /accounts/balances, la requête sera rejetée
- si vous essayez d’utiliser la méthode GET /accounts/end-iser-identity, la requête sera rejetée
- si vous essayer d’utiliser la méthode GET /trustedBeneficiaries, la requête sera rejetée => ce service n’est pas disponible pour les Banques Populaires : code erreur HTTP 501
.
Le client sélectionne les comptes dont il consent à vous donner l’accès sur votre APP
Vous demandez au client de sélectionner les comptes à vue et les opérations possibles sur ses comptes (récupération des soldes, récupération des transactions, etc.).
Transmission du consentement
Vous nous transmettez la liste des comptes à vue que le client vous a consenti via la méthode PUT /consents en fournissant votre jeton d’accès pour ce client (cf. cas d’usage « Gérer le consentement« ). Le code http 201 : created est retourné.
Vous précisez la liste des comptes à vue (IBAN) pour lesquels le client a consenti à transmettre les soldes et/ou les transactions
Vous précisez si le client a consenti à la récupération des bénéficiaires de confiance et à la récupération de son nom et prénom
Si vous avez déjà transmis les comptes consentis via la méthode PUT /consents, et que par la suite le client modifie son consentement, vous transmettrez la nouvelle liste des comptes consentis via la méthode PUT /consents, ce qui aura pour effet d’annuler et de remplacer le consentement précédent.
Si vous transmettez une liste vide de compte à vue consentis pour les soldes et pour les transactions et des indicateurs psuIdentity et trustedBeneficiaries à FAUX, cela revient à considérer qu’il n’y a pas de compte consenti.
Vous pouvez transmettre une liste de comptes à vue consentis sans avoir utilisé la méthode GET /accounts au préalable, dans le cas par exemple où le client vous a directement communiquer les IBAN de ses comptes à vue.
Second accès pour récupérer la liste des comptes à vue d’un client
Vous récupérez la liste des comptes à vue du client avec leur détail via un second accès à la méthode GET /accounts en fournissant votre jeton d’accès pour ce client (cf. cas d’usage « Lister les comptes« ).
Vous récupérez les informations suivantes :
- les comptes à vue consentis
- les cartes à débit différé adossées aux comptes à vue consentis
- les soldes des comptes à vue consentis
- les URI vers la méthode GET /accounts/balances pour les comptes à vue consentis
- les URI vers la méthode GET /accounts/transactions pour les comptes à vue consentis
- l’URI vers la méthode GET /end-user-identity si le flag « psuIdentity » = TRUE a été transmis via la méthode « PUT /consents«
Vous ne récupérez pas les informations suivantes :
- l’URI vers la méthode GET /trustedBeneficiaries
=> ce service n’est pas disponible.
Récupération des soldes et des transactions des comptes à vue consentis, récupération des encours et des facturettes pour les cartes à débit différé adossées aux comptes à vue consentis
Pour chaque compte à vue consenti, vous récupérez les soldes du compte via un accès à la méthode GET /accounts/balances en fournissant votre jeton d’accès pour ce client (cf. cas d’usage « Obtenir les soldes« ) et en utilisant l’URI communiquée précédemment par la méthode GET /accounts pour le « _links » « balances »
Pour chaque carte à débit différé d’un compte à vue consenti, vous récupérez les encours de la carte via un accès à la méthode GET /accounts/balances en fournissant votre jeton d’accès pour ce client (cf. cas d’usage « Obtenir les soldes« ) et en utilisant l’URI communiquée précédemment par la méthode GET /accounts pour le « _links » « balances »
Pour chaque compte à vue consenti, vous récupérez les transactions du compte via un accès à la méthode GET /accounts/transactions en fournissant votre jeton d’accès pour ce client (cf. cas d’usage « Obtenir les transactions« ) et en utilisant l’URI communiquée précédemment par la méthode GET /accounts pour le « _links » « transactions »
Pour chaque carte à débit différé d’un compte à vue consenti, vous récupérez les facturettes du compte via un accès à la méthode GET /accounts/transactions en fournissant votre jeton d’accès pour ce client (cf. cas d’usage « Obtenir les transactions« ) et en utilisant l’URI communiquée précédemment par la méthode GET /accounts pour le « _links » « transactions »
Si vous essayez d’utiliser la méthode GET /accounts/transactions pour un compte à vue non consenti ou pour une carte à débit différé adossée à un compte à vue non consenti, la requête sera rejetée
Si vous essayez d’utiliser la méthode GET /accounts/balances pour un compte à vue non consenti ou pour une carte à débit différé adossée à un compte à vue non consenti, la requête sera rejetée
Récupération de l’identité du client
Vous récupérez l’identité du PSU connecté via un accès à la m méthode GET /end-user-identity
Rafraîchissement des informations des comptes en batch
Pour chaque client et pour chaque compte à vue consenti ou carte à débit différé adossée à un compte à vue de ce client, vous pouvez rafraîchir les données du client (idem étapes « Second accès pour récupérer la liste des comptes à vue d’un client » et « Récupération des soldes et des transactions des comptes à vue consentis« )
La limite est de 4 accès batchs quotidiens maximum par PSU pour GET accounts par page d’accès
La limite est de 4 accès batchs quotidiens maximum par PSU/compte pour GET balances
La limite est de 4 accès batchs quotidiens maximum par PSU/compte pour GET transactions par page d’accès
La limite est de 4 accès batchs quotidiens maximum par PSU/carte pour GET balances
La limite est de 4 accès batchs quotidiens maximum par PSU/carte pour GET transactions par page d’accès
La limite est de 4 accès batchs quotidiens maximum par PSU pour GET end-user-identity par page d’accès
Rafraîchissement des informations des comptes à la demande du client connecté sur son mobile, pour le client et pour chaque compte consenti de ce client
Pour chaque client et pour chaque compte à vue consenti ou carte à débit différé adossée à un compte à vue de ce client, le client peut demander à rafraîchir ses données depuis votre application (idem étapes « Second accès pour récupérer la liste des comptes à vue d’un client » et « Récupération des soldes et des transactions des comptes à vue consentis« ).
Pas de limitation d’accès pour ce cas à l’inverse des accès batch.
Si le jeton de 180 jours a expiré, vous devez faire une demande de rafraîchissement du jeton pour le client connecté
1. Avec le client connecté sur votre application, vous soumettez une requête de rafraîchissement du jeton pour ce client (cf. cas d’usage « Rafraîchir votre jeton« )
2. Le client est redirigé vers un écran d’identification proposé par son établissement bancaire et dans lequel il saisira son identifiant de banque à distance. Si l’AISP fournit l’identifiant de banque à distance du client dans sa requête, l’étape suivante est directement déclenchée.
3. Le client est redirigé vers un écran d’authentification forte proposé par son établissement bancaire pour valider son identité. La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du client par l’établissement bancaire (SMS OTP, secur’pass, etc.). Elle dépend aussi de l’équipement du client sur lequel tourne l’APP du PISP utilisée par le client (PC ou mobile/tablette).
4. Le client est redirigé vers l’APP de l’AISP. L’AISP fournit lors de sa demande de récupération de jeton une URL call back : elle sera appelée par l’établissement bancaire.
5. Vous récupérez le jeton rafraîchi pour ce client et vous pourrez à nouveau accéder aux données du client pour 180 jours avec les méthodes de cette API
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 les API DSP2 exposées sont défaillantes, 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 :
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
Date de déploiement BPCE API Dev Portal & Sandbox |
Live
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 <cdetab = 13807> qui permet d’adresser le bon référentiel client.
- 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>.live.api.89c3.com/stet/psd2/oauth/token
avec par exemple <codetab> =
- 13807 pour BPGO
- 10548 pour Banque de Savoie
- 40978 pour Banque Palatine
avec :
- son certificat eIDAS QWAC de production
- le paramètre header (fallback: »1″)
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.13807.live.api.banquepopulaire.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.ibps.bpgo.banquepopulaire.fr/se-connecter/sso?service=cyber&cdetab=13807&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.13807.live.api.banquepopulaire.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 STET V1.4.2.17 / Part I / section 3.4.3
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)
- Suite à la mise en place de la nouvelle solution de banque en ligne, le fallback permet de rester sur les anciens écrans de la banque en ligne
- 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’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
- OTP SMS
- Clé physique (pour les entreprises)
Récupérer votre jeton
Principe
Votre 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 place OAUTH2.
Cinématique de récupération du jeton d’autorisation
1. Notre client (PSU) vous indique l’identité de sa banque teneur 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 la banque teneur de compte (ASPSP) et en utilisant la commande : GET /authorize.
Voir aussi la spécification de place STET V1.4.2.17 / Part I / section 3.4.3
3. La banque 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, la banque va rediriger le client (PSU) vers votre site en utilisant votre URL de « call-back » (redirection) que vous nous aurez transmise lors de votre enregistrement en tant que TPP consommateur de nos API,
- Soit lors du processus de « GO Live » via notre portail BPCE API (ancienne procédure);
- Soit via l’API register (procédure actuelle).
En effet, l’AISP doit préciser pour son APP consommatrice, une URL qui sera appelée par l’établissement bancaire :
- Si le client 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ée SANS le paramètre « scope ».
Voir aussi la spécification de place STET V1.4.2.17 / Part I / section 3.4.3
6. La banque 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, la banque teneur de compte va vous renvoyer une réponse HTTP200 (OK) contenant, entres autres, le jeton d’accès OAUTH2 (access_token).
Voir aussi la spécification de place STET V1.4.2.17 / Part I / section 3.4.3
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 « Comment tester l’API ? » > « Assemblage Sandbox ».
Pour plus de détail sur les données échangées, voir la rubrique « Comment tester l’API ?« .
Rafraîchir votre jeton
Principe
Le jeton d’autorisation ayant une durée de vie limitée, il vous est nécessaire de demander son rafraîchissement avant son expiration.
Règles de base
La banque teneur de compte (ASPSP) dispose au plus d’un jeton d’accès (access_token) et d’un jeton de rafraîchissement (refresh_token) valide 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 maximum) 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’autorisation 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’autorisation (access_token)
1. Vous demandez le renouvellement du jeton d’accès auprès de la banque
2. La banque initie le renouvellement du jeton d’accès
3. Elle récupère le certificat du TPP auprès du référentiel de place
4. Elle contrôle la validité et la non-révocation du certificat présenté
5. Elle contrôle la date de la dernière authentification (< 180 jours)
6. Elle vous transmet le nouveau jeton d’accès et l’ancien jeton de rafraîchissement
7. Vous stockez le jeton d’accès et l’ancien jeton de rafraîchissement de façon sûre
8. La banque invalide l’ancien jeton d’autorisation
Exemple
Un exemple de requête est fourni dans la rubrique « Comment tester l’API ? » > « Assemblage sandbox ».
Pour plus de détail sur les données échangées, voir la rubrique « Vue d’ensemble » > « Récupérer votre jeton ».
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 Register
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 :
Brand | App2App endpoint |
http://www.40978.live.api.palatine.fr/stet/psd2/oauth/authorize | |
http://www.<codetab>.live.api.banquepopulaire.fr/stet/psd2/oauth/authorize
(voir la liste des <codetab> sur la fiche produit API Banque Populaire) |
|
http://www.10548.live.api.banque-de-savoie.fr/stet/psd2/oauth/authorize | |
http://www.<codetab>.live.api.caisse-epargne.fr/stet/psd2/oauth/authorize
(voir la liste des <codetab> sur la fiche produit API Caisse d’Epargne) |
|
http://www.12579.live.api.banquebcp.fr/stet/psd2/oauth/authorize | |
http://www.42559.live.api.credit-cooperatif.coop/stet/psd2/oauth/authorize | |
http://www.30258.live.api.btp-banque.fr/stet/psd2/oauth/authorize | |
http://www.18919.live.api.natixis.com/stet/psd2/oauth/authorize |
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>.live.api.89c3.com/stet/psd2/oauth/authorize (ce qui peut être utile comme backup en cas de problème avec l’App2App)
Publications réglementaires
Période | Document |
Disponibilité des API DSP2 à date | Télécharger le document |
Statitiaques T1 2023 | Télécharger le document |
Statistiques T4 2022 | Télécharger le document |
Statistiques T3 2022 | Télécharger le document |
Statistiques T2 2022 | Télécharger le document |
Statistiques T1 2022 | Télécharger le document |
Statistiques T4 2021 | Télécharger le document |
Statistiques T3 2021 | Télécharger le document |
Statistiques T2 2021 | Télécharger le document |
Statistiques T1 2021 | Télécharger le document |
Statistiques T4 2020 | Télécharger le document |
Statistiques T3 2020 | Télécharger le document |
Statistiques T2 2020 | Télécharger le document |
Statistiques T1 2020 | Télécharger le document |
Catégories
/stet/psd2/v1.4.2/accounts/{accountResourceId}/balances
accountsBalances
Résumé
Retrieval of an account balances report (AISP)
Description
This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification
– The TPP has been registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
– The TPP has previously retrieved the list of available accounts for the PSU
The AISP requests the ASPSP on one of the PSU’s accounts.
The ASPSP answers by providing a list of balances on this account. – The ASPSP must provide at least the accounting balance on the account. – The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible. – Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.
Scopes
- extended_transaction_history
- cbpii
- aisp
Paramètres
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header « User-Agent » header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header « Referer » header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that « referer » (incorrect spelling) is to be used. The correct spelling « referrer » can be used but might not be understood. |
PSU-Accept | string header « Accept » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header « Accept-Charset » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header « Accept-Encoding » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header « Accept-Language » header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](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 an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Codes retour
200 | The ASPSP answers with a list of account balances |
204 | No content. |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Sorties
application/hal+json; charset=utf-8
application/json; charset=utf-8
Authentifications disponibles
OAuth 2.0
/stet/psd2/v1.4.2/accounts
accounts
Résumé
Retrieval of the PSU accounts (AISP)
Description
This call returns all payment accounts that are relevant the PSU on behalf of whom the AISP is connected.
Thanks to HYPERMEDIA, each account is returned with the links aiming to ease access to the relevant transactions and balances.
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results. – The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The TPP sends a request to the ASPSP for retrieving the list of the PSU payment accounts.
The ASPSP computes the relevant PSU accounts and builds the answer as an accounts list. The result may be subject to pagination in order to avoid an excessive result set. Each payment account will be provided with its characteristics.
Scopes
- aisp
- extended_transaction_history
- cbpii
Paramètres
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header « User-Agent » header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header « Referer » header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that « referer » (incorrect spelling) is to be used. The correct spelling « referrer » can be used but might not be understood. |
PSU-Accept | string header « Accept » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header « Accept-Charset » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header « Accept-Encoding » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header « Accept-Language » header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](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 an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Codes retour
200 | The ASPSP return a PSU context – listing the accounts that have been made available to the AISP by the PSU and, – for each of these accounts, the further transactions that have been enabled by the PSU through HYPERMEDIA links. |
204 | No content. |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Sorties
application/hal+json; charset=utf-8
application/json; charset=utf-8
Authentifications disponibles
OAuth 2.0
/stet/psd2/v1.4.2/accounts/{accountResourceId}/transactions
accountsTransactions
Résumé
Retrieval of an account transaction set (AISP)
Description
This call returns transactions for an account for a given PSU account that is specified by the AISP through an account resource identification.
The request may use some filter parameter in order to restrict the query – on a given imputation date range – past a given incremental technical identification
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.
– The TPP has been registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) is any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
– The TPP has previously retrieved the list of available accounts for the PSU
The AISP requests the ASPSP on one of the PSU’s accounts. It may specify some selection criteria.
The ASPSP answers by a set of transactions that matches the query. The result may be subject to pagination in order to avoid an excessive result set.
The default transaction set, in the absence of filter query parameter, has to be specified and documented by the implementation.
Scopes
- aisp
- cbpii
- extended_transaction_history
Paramètres
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
dateFrom | string query Inclusive minimal imputation date of the transactions. Transactions having an imputation date equal to this parameter are included within the result. |
dateTo | string query Exclusive maximal imputation date of the transactions. Transactions having an imputation date equal to this parameter are not included within the result. |
entryReferenceFrom | string query Specifies the value on which the result has to be computed. Only the transaction having a technical identification greater than this value must be included within the result |
entryReferenceto | string query Specifies the value on which the result has to be computed. Only the transaction having a technical identification less than or equal to this value must be included within the result |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header « User-Agent » header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header « Referer » header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that « referer » (incorrect spelling) is to be used. The correct spelling « referrer » can be used but might not be understood. |
PSU-Accept | string header « Accept » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header « Accept-Charset » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header « Accept-Encoding » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header « Accept-Language » header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](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 an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Codes retour
200 | Complete transactions response |
204 | No content. |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Sorties
application/hal+json; charset=utf-8
application/json; charset=utf-8
Authentifications disponibles
OAuth 2.0
/stet/psd2/v1.4.2/consents
consents
Résumé
Forwarding the PSU consent (AISP)
Description
In the mixed detailed consent on accounts
– the AISP captures the consent of the PSU
– then it forwards this consent to the ASPSP
This consent replaces any prior consent that was previously sent by the AISP.
– The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
The PSU specifies to the AISP which of his/her accounts will be accessible and which functionalities should be available.
The AISP forwards these settings to the ASPSP.
The ASPSP answers by HTTP201 return code.
Scopes
- extended_transaction_history
- cbpii
- aisp
Paramètres
Authorization (required) | string header Access token to be passed as a header |
access (required) | Access body List of consents granted to the AISP by the PSU. |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header « User-Agent » header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header « Referer » header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that « referer » (incorrect spelling) is to be used. The correct spelling « referrer » can be used but might not be understood. |
PSU-Accept | string header « Accept » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header « Accept-Charset » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header « Accept-Encoding » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header « Accept-Language » header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](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 an URL aiming to provide the relevant Qualified Certificate. |
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. |
503 | Service unavailable. |
Entrées
application/json
Sorties
application/hal+json; charset=utf-8
application/json; charset=utf-8
Authentifications disponibles
OAuth 2.0
/stet/psd2/v1.4.2/end-user-identity
endUserIdentity
Résumé
Retrieval of the identity of the end-user (AISP)
Description
This call returns the identity of the PSU (end-user).
– The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The AISP asks for the identity of the PSU. The ASPSP answers with the identity, i.e. first and last names of the end-user.
Scopes
- extended_transaction_history
- cbpii
- aisp
Paramètres
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header « User-Agent » header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header « Referer » header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that « referer » (incorrect spelling) is to be used. The correct spelling « referrer » can be used but might not be understood. |
PSU-Accept | string header « Accept » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header « Accept-Charset » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header « Accept-Encoding » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header « Accept-Language » header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](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 an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Codes retour
200 | The ASPSP returns the identity of the PSU |
204 | No content. |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
429 | Too many requests. |
500 | Internal server error. |
Sorties
application/hal+json; charset=utf-8
application/json; charset=utf-8
Authentifications disponibles
OAuth 2.0
/stet/psd2/v1.4.2/funds-confirmations
fundsConfirmations
Résumé
Payment coverage check request (CBPII)
Description
The CBPII can ask an ASPSP to check if a given amount can be covered by the liquidity that is available on a PSU cash account or payment card.
– The TPP has been registered by the Registration Authority for the CBPII role
– The TPP and the PSU have a contract that has been registered by the ASPSP – At this step, the ASPSP has delivered an « Authorization Code », a « Resource Owner Password » or a « Client Credential » OAUTH2 access token to the TPP (cf. § 3.4.2). – Each ASPSP has to implement either the « Authorization Code »/ »Resource Owner Password » or the « Client Credential » OAUTH2 access token model. – Doing this, it will edit the [security] section on this path in order to specify which model it has chosen
– The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code », « Resource Owner Password » or « Client Credential » access token which allows the ASPSP to identify the relevant PSU.
The CBPII requests the ASPSP for a payment coverage check against either a bank account or a card primary identifier.
The ASPSP answers with a structure embedding the original request and the result as a Boolean.
Scopes
- extended_transaction_history
- aisp
- cbpii
Paramètres
Authorization (required) | string header Access token to be passed as a header |
paymentCoverage (required) | PaymentCoverageRequestResource body parameters of a payment coverage request |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header « User-Agent » header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header « Referer » header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that « referer » (incorrect spelling) is to be used. The correct spelling « referrer » can be used but might not be understood. |
PSU-Accept | string header « Accept » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header « Accept-Charset » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header « Accept-Encoding » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header « Accept-Language » header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](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 an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Codes retour
200 | payment coverage request |
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. |
503 | Service unavailable. |
Entrées
application/json
Sorties
application/hal+json; charset=utf-8
application/json; charset=utf-8
Authentifications disponibles
OAuth 2.0
/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}/o-confirmation
paymentRequestOConfirmation
Résumé
Confirmation of a payment request or a modification request using an OAUTH2 Authorization code grant (PISP)
Description
The PISP confirms one of the following requests or modifications:
– payment request on behalf of a merchant
– transfer request on behalf of the account’s owner
– standing-order request on behalf of the account’s owner
The ASPSP answers with a status of the relevant request and the subsequent Credit Transfer. – The TPP has been registered by the Registration Authority for the PISP role
– The TPP was provided with an OAUTH2 « Client Credential » access token by the ASPSP (cf. § 3.4.2).
– The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3) – The ASPSP has answered with a location link to the saved Payment Request (cf. § 4.5.4) – The TPP has retrieved the saved request in order to get the relevant resource Ids (cf. § 4.6).
– The PSU has been authenticated by the ASPSP through an OAUTH2 authorization code grant flow (REDIRECT approach) and the PISP got the relevant token
– The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its « OAUTH2 Authorization Code » access token Once the PSU has been authenticated through an OAUTH2 authorization code grant flow (REDIRECT approach), it is the due to the PISP to confirm the Request to the ASPSP in order to complete the process flow.
The ASPSP must wait for confirmation before executing the subsequent Credit Tranfer.
Scopes
- extended_transaction_history
- cbpii
- aisp
- pisp
Paramètres
Authorization (required) | string header Access token to be passed as a header |
paymentRequestResourceId (required) | string path Identification of the Payment Request Resource |
confirmationRequest (required) | ConfirmationResource body Parameters needed for confirmation of the Payment Request, especially in « EMBEDDED-1-FACTOR » approach Even though there is no parameter, a Json (void) body structure must be provided. |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header « User-Agent » header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header « Referer » header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that « referer » (incorrect spelling) is to be used. The correct spelling « referrer » can be used but might not be understood. |
PSU-Accept | string header « Accept » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header « Accept-Charset » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header « Accept-Encoding » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header « Accept-Language » header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](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 an URL aiming to provide the relevant Qualified Certificate. |
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 Payment Request enriched with the status report |
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. |
409 | Conflict. The request could not be completed due to a conflict with the current state of the target resource. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Entrées
application/json
Sorties
application/hal+json; charset=utf-8
application/json; charset=utf-8
Authentifications disponibles
OAuth 2.0
/stet/psd2/v1.4.2/trusted-beneficiaries
trustedBeneficiaries
Résumé
Retrieval of the trusted beneficiaries list (AISP)
Description
This call returns all trusted beneficiaries that have been set by the PSU.
Those beneficiaries can benefit from an SCA exemption during payment initiation.
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.
– The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
The AISP asks for the trusted beneficiaries list.
The ASPSP answers with a list of beneficiary details structure.
Scopes
- extended_transaction_history
- cbpii
- aisp
Paramètres
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header « User-Agent » header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header « Referer » header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that « referer » (incorrect spelling) is to be used. The correct spelling « referrer » can be used but might not be understood. |
PSU-Accept | string header « Accept » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header « Accept-Charset » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header « Accept-Encoding » header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header « Accept-Language » header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](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 an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Codes retour
200 | The ASPSP returns the list of whitelisted beneficiaries |
204 | No content. |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
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. |
Sorties
application/hal+json; charset=utf-8
application/json; charset=utf-8
Authentifications disponibles
OAuth 2.0
Catégories
-
Cas d'usage
-
Comment tester l'API
Obtenir la liste des comptes
Obtenir la liste des comptes à vue et des cartes à débit différé
Cas d’usage
Ce service permet de récupérer la liste des comptes à vue et cartes à débit différé du client (*).
Chaque compte ou carte est retourné avec les liens permettant de consulter les soldes ou les encours ainsi que les transactions associées à celui-ci.
Le resourceId fourni pour chaque compte et carte servira de paramètre pour les requêtes de récupération de soldes et de transactions.
Une pagination de la liste renvoyée peut être faite si le nombre de comptes ou cartes est élevé, dans ce cas des liens donnant accès à la première page, la précédente, la suivante et la dernière page faciliteront la consultation des résultats.
Les accès à cette méthode sont limités à 4 accès batch maximum par jour calendaire, pour un client donné, hors pagination.
En résumé, ce service permet :
- de lister tous les comptes à vue et cartes à débit différé adossées à ces derniers ;
- de récupérer les soldes des comptes à vue
- de récupérer les encours des cartes à débit différé (*)
- de récupérer l’URI pour la méthode « GET /end-user-identity »
- de récupérer les URI pour les méthodes « GET /accounts/balances » et « GET /accounts/transactions »
(*) Cette API ne remonte que les cartes à débit différée actives et qui ont servi (présence de facturette CB sur le compte support de la carte) au moins une fois dans les deux derniers mois.
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 « Vue d’ensemble » > « Récupérer votre jeton« ).
Requête
Requête « GET /accounts »
Voir aussi la spécification de place STET V1.4.2.17 / Part II / section 4.2 / page 27
Paramètres obligatoires ou facultatifs du body requis pour l’appel de ce service
Paramètre facultatif : PSU-IP-ADDRESS => à alimenter si le client est connecté.
Résultat retourné
Si vous n’avez pas transmis de compte consenti par le client via la méthode PUT/consents ou que tous les comptes consentis ont été révoqués suite au dernier appel à la méthode PUT /consents :
- Cet appel vous permet
- de récupérer la liste de tous les comptes du client sans leurs soldes, sans les URI pour les méthodes GET /accounts/balances, GET /accounts/transactions et GET /end-user-identity
Si avez transmis au moins un compte consenti par le client via la méthode PUT /consents et que tous les comptes consentis n’ont pas été révoqués suite au dernier appel à la méthode PUT /consents.
- Cet appel vous permet
- de récupérer la liste de tous les comptes consentis du client avec :
- leurs soldes si le compte fait partie de la liste « balances » transmise via la méthode PUT /consents
- l’URI pour la méthode GET /accounts/balances si le compte fait partie de la liste « balances » transmise via la méthode PUT /consents
- l’URI pour la méthode GET /accounts/transactions si le compte fait partie de la liste « transactions » transmise via la méthode PUT /consents
- de récupérer la liste de toutes les cartes à débit différé (*) adossées aux comptes consentis (y compris s’il s’agit d’un compte joint) avec :
- leurs encours si la carte à débit différée est adossée à un compte à vue qui fait partie de la liste « balances » transmise via la méthode PUT /consents
- l’URI pour la méthode GET /accounts/balances si la carte à débit différé est adossées à un compte à vue qui fait partie de la liste « balances » transmise via la méthode PUT /consents
- l’URI pour la méthode GET /accounts/transactions si la carte à débit différé est adossée à un compte à vue qui fait partie de la liste « transactions » transmise via la méthode PUT /consents
- de récupérer l’URI pour la méthode « GET /end-user-identity » si la rubrique « psuIdentity » a été alimentée avec la valeur TRUE via la méthode PUT /consents
- de récupérer la liste de tous les comptes consentis du client avec :
- Cet appel ne vous permet pas
- de récupérer les comptes à vue et les cartes à débit différés pour les comptes à vue non consentis
Une pagination de la liste renvoyée peut être faite si le nombre de comptes à vue ou de cartes à débit différé est élevé, dans ce cas des liens de navigation donnant accès à la première page, la précédente, la suivante et la dernière page faciliteront la consultation des résultats.
Un lien sera également présent pour revenir à la page obtenue juste 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 donné (modulo la pagination éventuelle). En revanche, lorsque c’est le client connecté qui interroge directement ses comptes à vue, le nombre d’accès n’est pas limité.
La propriété « psuStatus » prend la valeur « Account Co-Holder » dès lors que le client n’est pas le seul titulaire du compte
(*) L’API AISP des Banques Populaires, Banque de Savoie et Banque Palatine ne remonte que les cartes à débit différée actives et qui ont servi (présence de facturette CB sur le compte support de la carte) au moins une fois dans les deux derniers mois : les cartes à débit différé actives qui n’ont pas d’encours carte dans le mois courant ni dans le mois précédent ne sont pas remontées par la requête « GET /accounts ».
Exemple sans consentement donné via PUT /consents
Requête
GET /stet/psd2/v1.4.2/accounts/
Résultat
Status code : 200
Body
{
« _links »: { « last »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts?page=last » }, « self »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » }, « first »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/end-user-identity » }, « endUserIdentity »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » } }, « accounts »: [ { « cashAccountType »: « CACC », « accountId »: { « iban »: « FR7613807008043001965409135 » « currency »: « EUR », }, « resourceId »: « 038-CPT30019654091 », « product »: « COMPTE COURANT », « _links »: {}, « usage »: « ORGA », « psuStatus »: « Account Holder », « name »: « Tech-N Co », « bicFi »: « CCBPFRPPNAN », « details »: « COMPTE COURANT » } ]}
Remarques :
- Le champ « currency » a été déplacé au niveau de l’ »accountId« .
Exemple avec consentement donné via PUT /consents et restitution carte à débit différé
Requête
GET /stet/psd2/v1.4.2/accounts/
Résultat
Status code : 200
Body
{
« _links »: {
« last »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts?page=last » }, « self »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » }, « first »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » }, « endUserIdentity »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/end-user-identity » } }, « accounts »: [ { « cashAccountType »: « CACC », « accountId »: { « iban »: « FR7613807008063031966574122 », « currency »: « EUR » }, « resourceId »: « 038-CPT30319665741 », « product »: « COMPTE CHEQUE », « balances »: [ { « balanceType »: « VALU », « name »: « Solde en Valeur », « balanceAmount »: { « amount »: « 0 », « currency »: « EUR » }, « referenceDate »: « 2020-06-05 » }, { « balanceType »: « CLBD », « name »: « Solde Comptable », « balanceAmount »: { « amount »: « 0 », « currency »: « EUR » }, « referenceDate »: « 2020-06-04 » }, { « balanceType »: « OTHR », « name »: « Solde TP », « balanceAmount »: { « amount »: « 0 », « currency »: « EUR » } } ], « _links »: { « balances »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30319665741/balances » }, « transactions »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30319665741/transactions » } }, « usage »: « PRIV », « psuStatus »: « Account Holder », « name »: « BARDE ADAM », « bicFi »: « CCBPFRPPNAN », « details »: « COMPTE CHEQUE » }, { « cashAccountType »: « CACC », « accountId »: { « iban »: « FR7613807008063031966574219 », « currency »: « EUR » }, « resourceId »: « 038-CPT30319665742 », « product »: « COMPTE COURANT », « balances »: [ { « balanceType »: « VALU », « name »: « Solde en Valeur », « balanceAmount »: { « amount »: « -2894.05 », « currency »: « EUR » }, « referenceDate »: « 2020-06-05 » }, { « balanceType »: « CLBD », « name »: « Solde Comptable », « balanceAmount »: { « amount »: « -2894.05 », « currency »: « EUR » }, « referenceDate »: « 2020-06-04 » }, { « balanceType »: « OTHR », « name »: « Solde TP », « balanceAmount »: { « amount »: « -2894.05 », « currency »: « EUR » } } ], « _links »: { « balances »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30319665742/balances » }, « transactions »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30319665742/transactions » } }, « usage »: « ORGA », « psuStatus »: « Account Holder », « name »: « SARL UNI PICCOLO », « bicFi »: « CCBPFRPPNAN », « details »: « COMPTE COURANT » }, { « cashAccountType »: « CARD », « accountId »: { « other »: { « identification »: « C01WcBfYTK70wJJ5LpsMI3EGQ== », « schemeName »: « CPAN », « issuer »: « 13807 » }, « currency »: « EUR » }, « resourceId »: « 038-GFCC01WcBfYTK70wJJ5LpsMI3EGQ », « product »: « Visa Classic », « balances »: [ { « balanceType »: « OTHR », « name »: « Encours », « balanceAmount »: { « amount »: « 0 », « currency »: « EUR » }, « referenceDate »: « 2020-06-30 » }, { « balanceType »: « OTHR », « name »: « Dernier encours prélevé », « balanceAmount »: { « amount »: « 78.65 », « currency »: « EUR » }, « referenceDate »: « 2020-05-31 » } ], « _links »: { « balances »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-GFCC01WcBfYTK70wJJ5LpsMI3EGQ/balances » }, « transactions »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-GFCC01WcBfYTK70wJJ5LpsMI3EGQ/transactions » } }, « usage »: « PRIV », « psuStatus »: « Account Holder », « name »: « M ADAM BARDE XX9351 », « linkedAccount »: « 038-CPT30319665741 », « bicFi »: « CCBPFRPPNAN », « details »: « CB VISA FACELIA DEBIT DIFFERE » }, { « cashAccountType »: « CARD », « accountId »: { « other »: { « identification »: « C01mS9kXqK80z5X19/E7WmZjw== », « schemeName »: « CPAN », « issuer »: « 13807 » }, « currency »: « EUR » }, « resourceId »: « 038-GFCC01mS9kXqK80z5X19_E7WmZjw », « product »: « Visa Classic », « balances »: [ { « balanceType »: « OTHR », « name »: « Encours », « balanceAmount »: { « amount »: « 0 », « currency »: « EUR » }, « referenceDate »: « 2020-06-30 » }, { « balanceType »: « OTHR », « name »: « Dernier encours prélevé », « balanceAmount »: { « amount »: « 156.27 », « currency »: « EUR » }, « referenceDate »: « 2020-05-31 » } ], « _links »: { « balances »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-GFCC01mS9kXqK80z5X19_E7WmZjw/balances » }, « transactions »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-GFCC01mS9kXqK80z5X19_E7WmZjw/transactions » } }, « usage »: « PRIV », « psuStatus »: « Account Holder », « name »: « M ADAM BARDE XX4620 », « linkedAccount »: « 038-CPT30319665741 », « bicFi »: « CCBPFRPPNAN », « details »: « VISA INTERNATIONALE DB DIFFERE » } ]}
(Cas du persona Adam – D0999994I0)
Remarques :
- Le champ “connectedPsu” a été supprimé et remplacé par le links »endUserIdentity »
Exemple de pagination
Requête
GET /stet/psd2/v1.4.2/accounts?page=1
Résultat
Status code : 200
Body
« accounts »: [ { « cashAccountType »: « CACC », »accountId »: { « iban »: « FR7613807008043099888880699″, »currency »: « EUR » }, « resourceId »: « 038-CPT30998888806″, »product »: « COMPTE CHEQUE », »balances »: [ { « balanceType »: « VALU », »name »: « Solde en Valeur », »balanceAmount »: { « amount »: « 6.78 », « currency »: « EUR » }, « referenceDate »: « 2020-06-05 »}, { « balanceType »: « CLBD », »name »: « Solde Comptable », »balanceAmount »: { « amount »: « 6.78 », « currency »: « EUR » }, »referenceDate »: « 2020-06-04 »}, { « balanceType »: « OTHR », »name »: « Solde TP », »balanceAmount »: { « amount »: « 6.78 », »currency »: « EUR » } } ], « _links »: { « balances »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888806/balances » }, « transactions »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888806/transactions » } }, « usage »: « PRIV », « psuStatus »: « Nominee », « name »: « Compte mensualités », « bicFi »: « CCBPFRPPNAN », « details »: « COMPTE CHEQUE » }, { « cashAccountType »: « CACC », « accountId »: { « iban »: « FR7613807008043099888880799 », « currency »: « EUR » }, « resourceId »: « 038-CPT30998888807 », « product »: « COMPTE CHEQUE », « balances »: [ { « balanceType »: « VALU », « name »: « Solde en Valeur », « balanceAmount »: { « amount »: « 7.6 », « currency »: « EUR » }, « referenceDate »: « 2020-06-05 » }, { « balanceType »: « CLBD », « name »: « Solde Comptable », « balanceAmount »: { « amount »: « 7.6 », « currency »: « EUR » }, »referenceDate »: « 2020-06-04 » }, { « balanceType »: « OTHR », « name »: « Solde TP », « balanceAmount »: { « amount »: « 7.6 », « currency »: « EUR » } } ], « _links »: {« balances »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888807/balances » }, »transactions »: { « templated »: false, »href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888807/transactions » } }, « usage »: « PRIV », »psuStatus »: « Successor On Death », »name »: « Compte perso », »bicFi »: « CCBPFRPPNAN », »details »: « COMPTE CHEQUE » }, { « cashAccountType »: « CACC », »accountId »: { « iban »: « FR7613807008043099888880899 », « currency »: « EUR » }, « resourceId »: « 038-CPT30998888808 », « product »: « COMPTE CHEQUE », « balances »: [ { « balanceType »: « VALU », « name »: « Solde en Valeur », »balanceAmount »: { « amount »: « 8.8 », « currency »: « EUR » }, « referenceDate »: « 2020-06-05 » }, { « balanceType »: « CLBD », »name »: « Solde Comptable », »balanceAmount »: {« amount »: « 8.8 », »currency »: « EUR »}, »referenceDate »: « 2020-06-04 »},{« balanceType »: « OTHR », »name »: « Solde TP », »balanceAmount »: { « amount »: « 8.8 », »currency »: « EUR » } } ], « _links »: { « balances »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888808/balances » }, « transactions »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888808/transactions » }}, « usage »: « PRIV », « psuStatus »: « Trustee », « name »: « Retrait et Cheques », « bicFi »: « CCBPFRPPNAN », « details »: « COMPTE CHEQUE 8 » }, { « cashAccountType »: « CACC », « accountId »: { « iban »: « FR7613807008043099888880999 », « currency »: « EUR » }, « resourceId »: « 038-CPT30998888809 », « product »: « COMPTE CHEQUE », « balances »: [ { « balanceType »: « VALU », « name »: « Solde en Valeur », « balanceAmount »: { « amount »: « 9.9 », « currency »: « EUR » }, « referenceDate »: « 2020-06-05 » }, { « balanceType »: « CLBD », « name »: « Solde Comptable », « balanceAmount »: { « amount »: « 9.9 », « currency »: « EUR » }, »referenceDate »: « 2020-06-04 »},{ « balanceType »: « OTHR », »name »: « Solde TP », »balanceAmount »: { « amount »: « 9.9 », »currency »: « EUR » } } ], « _links »: { « balances »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888809/balances » }, « transactions »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888809/transactions » } }, « usage »: « PRIV », « psuStatus »: « Trustee », »name »: « Retrait et Cheques », »bicFi »: « CCBPFRPPNAN », »details »: « COMPTE CHEQUE 9 » }, { « cashAccountType »: « CACC », »accountId »: {« iban »: « FR7613807008043099888881099″, »currency »: « EUR »}, « resourceId »: « 038-CPT30998888810″, »product »: « COMPTE CHEQUE », »balances »: [ { « balanceType »: « VALU », « name »: « Solde en Valeur », « balanceAmount »: { « amount »: « 10.10 », « currency »: « EUR » }, « referenceDate »: « 2020-06-05 » }, { « balanceType »: « CLBD », « name »: « Solde Comptable », « balanceAmount »: { « amount »: « 10.10 », »currency »: « EUR » }, »referenceDate »: « 2020-06-04 » }, { « balanceType »: « OTHR », « name »: « Solde TP », « balanceAmount »: { « amount »: « 10.10 », « currency »: « EUR » } } ], « _links »: { « balances »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888810/balances » }, « transactions »: { « templated »: false, « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30998888810/transactions » } }, « usage »: « PRIV », « psuStatus »: « Trustee », « name »: « Retrait et Cheques », « bicFi »: « CCBPFRPPNAN », « details »: « COMPTE CHEQUE 10 » } ], « _links »: { « next »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts?page=3 » }, « last »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts?page=last » }, « prev »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » }, « self »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts?page=2 » }, « first »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » }, « endUserIdentity »: { « href »: « https://www.rs-sandbox.api.89c3.com/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 ».
Codes erreurs
Voici la liste de descriptions des codes erreurs de ce service. Il y a une annotation rouge pour ceux étant définis CFONB.
Erreur | Description de l’erreur |
AC01 (CFONB) | IncorrectAccountNumber : le numéro de compte est incorrect ou inconnu |
AC04(CFONB) | ClosedAccountNumber : le compte est clos |
AC06(CFONB) | BlockedAccount : le compte est bloqué / fait l’objet d’une opposition |
BE05(CFONB) | UnrecognisedInitiatingParty : l’AISP est inconnu |
BADS | BadScope : l’appel au service a été fait avec un jeton CBPII (AISP attendu) |
INTE | InternalError : il y a une erreur interne de traitement |
INTS | InternalServerError : il y a une erreur interne de communication avec le SI |
IPGN | InvalidPageNumber : le numéro de page est invalide |
NAAC | No avalaible accounts : absence de comptes éligibles ou consentis |
NGAC | NotGrantedAccount : le compte n’est pas consenti |
NIMP | NotImplemented : le mauvais verbe est appelé (GET attendu) |
TMRQ | TooManyRequest : le nombre de requêtes possibles a été dépassé |
IPSU | InvalidPSU : Numéro d’abonné non référencé ou abonnement banque à distance résilié |
Tests d’acceptance
Ces cas de tests ont pour objectif de vous permettre d’effectuer un minimum de tests pour prendre en main cette API et y accéder depuis votre application.
Description du test | Jeu de données |
Récupération de tous les comptes d’un client (au moins 2 doivent être présents au niveau de l’ASPSP)
=> Vérification des liens présents dans le résultat de la requête (lien self, soldes et transactions) |
Persona :
Alix – D0999992I0 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution de trois comptes de paiement et trois cartes à débit différée |
Récupération de plusieurs comptes liés au client et vérification que l’ASPSP gère correctement le mécanisme de pagination
=> Vérification des liens optionnels premier, précédent, suivant, dernier. |
Persona :
Marc – D0999990I0 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution de ses trois comptes sur la même page |
Récupération de plusieurs comptes et cartes liés au client et vérification que l’ASPSP gère correctement le mécanisme de pagination
=> Vérification des liens optionnels premier, précédent, suivant, dernier. |
Persona :
Adam – D0999994I0 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution de deux comptes et de deux cartes à débit différé |
Requête HTTP avec un jeton d’accès non autorisé pour la ressource (scope erroné) | Persona :
Marc – D0999990I0 Prérequis : scope OAuth2 <> aisp Résultat : réponse HTTP403 => accès à la ressource refusé message d’erreur : BADS |
Passage d’une requête HTTP POST | Persona :
Marc – D0999990I0 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP405 => méthode non autorisée |
Transmettre la liste des comptes
Gérez et transmettez la liste des comptes à vue consentis par le PSU pour la consultation des soldes et/ou des transactions !
Cas d’usage
Ce service permet d’enregistrer le consentement du client.
Ce consentement contient le détail des accès consentis par le client.
Quatre types d’accès peuvent être définis :
- « balances » => accès aux soldes d’un ou plusieurs comptes du client
- « transactions » => accès aux transactions d’un ou plusieurs comptes du client
- « psuIdentity » => accès aux données d’identité du client (nom et prénom)
- « trustedBeneficiaries » => accès à la liste des bénéficiaires de confiance du client : cette fonctionnalité n’est pas disponible (cf. « Limitations » du produit)
Un enregistrement du consentement est réalisé pour un client donné.
Chaque nouvel appel au service d’enregistrement du consentement pour un client donné, annulera et remplacera le consentement précédent le cas échéant.
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 les soldes reste actif.
Le consentement est vérifié à chaque requête passée.
En résumé, ce service permet de transmettre les IBAN des comptes à vue pour lesquels le client vous a autorisé à consulter le détail des soldes et / ou des transactions ainsi que son identité.
Prérequis
Vous pouvez récupérer la liste des comptes à vue du client après avoir appelé une première fois la requête GET /accounts : vous y trouverez l’IBAN associé à chaque compte à vue, c’est à dire tel que « accountId« : {« iban »: » » }.
Cependant si vous connaissez déjà le ou les IBAN des comptes à vue du client, vous pouvez nous les transmettre directement via la méthode PUT /consents. Dans ce cas, 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 « Vue d’ensemble » > « Récupérez votre jeton« ).
Requête
Requête « PUT /consents »
Paramètres obligatoires ou facultatifs du body requis pour l’appel de ce service
balances : tableau obligatoire mais qui peut être vide : liste des comptes accessibles pour la fonctionnalité « soldes » ⇒ iban – obligatoire : Numéro de compte bancaire international (IBAN)
transactions : tableau obligatoire mais qui peut être vide : liste des comptes accessibles pour la fonctionnalité « transactions » ⇒ iban – obligatoire : Numéro de compte bancaire international (IBAN)
trustedBeneficiaries : obligatoire : valeur (true ou false) indiquant si l’accès à la liste des bénéficiaires de confiance est autorisé pour l’AISP par le client
psuIdentity : obligatoire : valeur (true ou false) indiquant si l’accès à l’identité du client(prénom, nom) est autorisé pour l’AISP par le client
Paramètre facultatif : PSU-IP-ADDRESS => à alimenter si le client est connecté
Résultat retourné
Cet appel permet d’enregistrer les comptes à vue que le client vous a consentis.
Le client peut vous consentir 4 types d’accès :
- « psuIdentity » ⇒ accès à l’identité du client (nom et prénom pour un client de type « particulier »)
- L’identité du client est accessible via la méthode GET /end-user-identity uniquement si le client l’a consenti
- « transactions » ⇒ accès aux transactions d’un ou plusieurs comptes à vue et aux factures des cartes à débit différé qui s’y rattachent
- Les transactions des comptes à vue et les facturettes des cartes à débit différé qui s’y rattachent sont accessibles via la méthode GET /accounts et via la méthode GET /accounts/balances pour les comptes consentis uniquement
- « balances » ⇒ accès aux soldes d’un ou plusieurs comptes à vue et aux cartes à débit différé qui s’y rattachent :
- Les soldes des comptes à vue et les encours carte des cartes à débit différé qui s’y rattachent sont accessibles via la méthode GET /accounts et via la méthode GET /accounts/balances pour les comptes consentis uniquement
- « trustedBeneficiaries » ⇒ accès à la liste des bénéficiaires de confiance
- Cette fonctionnalité n’est pas disponible
Il est possible d’appeler plusieurs fois la méthode PUT /consents si le client a modifié son consentement : chaque nouvel appel de la méthode PUT /consents annule et remplace les consentements précédents.
Le consentement du client est vérifié à chaque requête passée pour les méthodes GET /accounts, GET /accounts/balances et GET /accounts/transactions.
Lorsqu’un compte à vue est consenti pour l’accès « balances » :
- Les cartes à débit différés sont récupérables via la méthode GET /accounts
- Les encours de ces cartes sont récupérables via la méthode GET /accounts ou via la méthode GET /accounts/balances.
Lorsqu’un compte à vue est consenti pour l’accès « transactions » :
- Les cartes à débit différés sont récupérables via la méthode GET /accounts
- Les facturettes de ces cartes sont récupérables via la méthode GET /accounts/balances.
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, dans ce cas cela signifie que le client a révoqué tous les comptes consentis
Si aucun compte à vue 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 à vue mais l’accès au soldes et transactions des comptes à vue et l’accès aux cartes à débit différé et à leurs encours et facturettes n’est pas/plus possible.
Exemple
Requête
PUT /stet/psd2/v1.4.2/consents/
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 V1.4.2.17 / Part III / section 6.2 / page 7
Résultat
Status code : 201
Le service consentement renvoie un code « 201 – Created » lors de l’enregistrement du consentement
Le service consentement renvoie un code « 403 – Forbidden » en cas d’échec de l’enregistrement
Body
{« balances »: [{« iban »: « FR7613807008043001965405158 »},{« iban »: « FR7613807008043001965405255 »},{« iban »: « FR7613807008043001965405352 »}],
« transactions »: [{« iban »: « FR7613807008043001965405158 »},{« iban »: « FR7613807008043001965405255 »},{« iban »: « FR7613807008043001965405352″}], »trustedBeneficiaries »: true, »psuIdentity »: true}
(cas du persona Marc – D0999990I0)
Remarque :
- le champ « currency » a été ajouté au niveau de l’ »AccountIdentification »
Codes erreurs
Voici la liste de descriptions des codes erreurs de ce service. Il y a une annotation rouge pour ceux étant définis CFONB.
Erreur | Description de l’erreur |
AC01
(CFONB) |
IncorrectAccountNumber : l’IBAN est incorrect ou inconnu |
AC04
(CFONB) |
ClosedAccountNumber : le compte est clos |
AC06
(CFONB) |
BlockedAccount : le compte est bloqué / fait l’objet d’une opposition |
BE05
(CFONB) |
UnrecognisedInitiatingParty : l’AISP est inconnu |
BADS | BadScope : l’appel au service a été fait avec un jeton CBPII (AISP attendu) |
ENDE | EntriesDatesError : une ou des dates sont erronées |
IPGN | InvalidPageNumber : le numéro de page est invalide |
INTE | InternalError : il y a une erreur interne de traitement |
INTS | InternalServerError : il y a une erreur interne de communication avec le SI |
NGAC | NotGrantedAccount : le compte n’est pas consenti |
NIMP | NotImplemented : le mauvais verbe est appelé (GET attendu) |
TQMR | TooManyRequest : le nombre de requêtes possibles a été dépassé |
RENF | ReferenceNotFound : la référence de la transaction est inexistante |
IPSU | InvalidPSU : Numéro d’abonné non référencé ou abonnement banque à distance résilié |
FF01 | Format du corps de la requête (Body) incorrect (Body vide, donnée obligatoire manquante)² |
NAAC | NotAvailableAccounts : absence de comptes éligibles |
CDNA | CardNotAvailable : la carte à débit différé n’est pas ou plus accessible |
Tests d’acceptance
Ces cas de tests ont pour objectif de vous permettre d’effectuer un minimum de tests pour prendre en main cette API et y accéder depuis votre application.
Description du test | Jeu de données et Résultat attendu |
Enregistrement de données de consentement d’un client | Persona :
Marc – D0999990I0 Prérequis : scope OAuth2 = aisp IBANs : FR7613807008043001965405158 FR7613807008043001965405255 FR7613807008043001965405352 Résultat : réponse HTTP 201 => OK, consentement enregistré |
Enregistrement de données de consentement d’un client | Persona :
Adam – D0999994I0 Prérequis : scope OAuth2 = aisp IBANs : FR7613807008063031966574122 FR7613807008063031966574219 Résultat : réponse HTTP 201 => OK, consentement enregistré |
Passage d’une requête HTTP avec un jeton d’accès non autorisé pour la ressource (scope erroné) | Persona :
Marc – D0999990I0 Prérequis : scope OAuth2 <> aisp IBANs : FR7613807008043001965405158 FR7613807008043001965405255 FR7613807008043001965405352 Résultat : réponse HTTP 403 => accès à la ressource refusé message d’erreur : BADS |
Passage d’une requête HTTP POST | Persona :
Marc – D0999990I0 Prérequis : scope OAuth2 = aisp IBANs : FR7613807008043001965405158 FR7613807008043001965405255 FR7613807008043001965405352 Résultat : réponse HTTP 405 => méthode non autorisée |
Obtenir les soldes
Obtenez les soldes d’un compte à vue ou les encours des cartes à débit différé adossées à ce dernier !
Cas d’usage
Ce service permet de récupérer la liste des soldes d’un compte à vue ou les encours d’une carte à débit différé du client.
Ce service fait suite à la restitution de la liste des comptes et cartes d’un client : un resourceId correspondant à un compte ou une carte doit être fourni pour obtenir la liste des soldes ou encours.
3 types de soldes seront retournés dans le cas d’un compte passé en paramètre :
- Solde en valeur (« VALU » dans la norme STET) => solde affiché par rapport à une date de valeur
- Solde Comptable (« CLBD » dans la norme STET) => solde comptable en fin de période (fin de semaine, fin de mois, fin de trimestre, fin de semestre, fin d’année)
- Solde TP (« OTHR » dans la norme STET) => solde instantané (évolue en temps réel à chaque écriture sur le compte)
3 types d’encours seront retournés dans le cas d’une carte passée en paramètre :
- Encours => montant des facturettes reportées au mois suivant
- Encours terminé non prélevé => correspond au montant des facturettes du mois courant non encore comptabilisées
- Encours terminé prélevé => correspond au montant des facturettes du mois précédent
Une pagination de la liste renvoyée peut être faite s’il y a beaucoup de données à afficher, dans ce cas des liens donnant accès à la première page, la précédente, la suivante et la dernière page faciliteront la consultation des résultats.
Les accès à cette méthode sont limités à 4 accès batch maximum par jour calendaire, pour un client et pour un compte / une carte à débit différé donnés.
En résumé, ce service permet de lister les soldes d’un compte à vue du client ou de lister les encours d’une carte à débit différé adossée à ce compte à vue.
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 « Vue d’ensemble » > « Récupérer votre jeton« ).
Pour récupérer le solde d’un compte à vue :
- 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 à vue 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 à vue
Pour récupérer les encours d’une carte à débit différé adossée à un compte à vue :
- L’IBAN du compte à vue auquel est adossée la carte à débit différé 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 la carte à débit différé, est récupéré via le résultat de la requête GET /accounts dans la rubrique « resourceId » pour la carte à débit différé, c’est à dire : tel que « accountId »: {« other »: »{« schemeName »: CPAN}} avec « linkedAccount » qui correspond au « resourceId » du compte à vue avec le « resourceId » du compte à vue récupéré via la requête GET /accounts et 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 » de la carte à débit différé.
Requête
Requête « GET /accounts/{accountResourceId}/balances »
Voir aussi la spécification de place STET V1.4.2.17 / Part II / Section 4.3.4 / page 31
Paramètres obligatoires ou facultatifs du body requis pour l’appel de ce service
Paramètre accountResourceId : compte à vue pour lequel on veut consulter les soldes ou carte à débit différé pour laquelle on veut consulter les encours, cette donnée correspond à la rubrique « resourceId » obtenue dans la page de résultat de la requête GET /accounts.
Paramètre facultatif : PSU-IP-ADDRESS => à alimenter si le PSU est connecté.
Résultat retourné
Cet appel permet de récupérer :
- la liste des soldes pour le compte à vue passé en paramètre
- ou la liste des encours de la carte à débit différé passée en paramètre.
3 types de soldes seront retournés dans le cas d’un compte à vue passé en paramètre :
Solde en valeur (« VALU » dans la norme STET) | => solde affiché par rapport à une date de valeur. Le solde en valeur n’est pas disponible pendant l’exécution du batch comptable (en principe entre 21h et 21h50). |
Solde Comptable (« CLBD » dans la norme STET) | => solde comptable en fin de période (fin de semaine, fin de mois, fin de trimestre, fin de semestre, fin d’année). Pour un compte nouvellement créé, le solde comptable n’est pas disponible avant l’exécution du premier batch comptable. |
Solde TP (« OTHR » dans la norme STET) | => solde instantané (évolue en temps réel à chaque écriture sur le compte) |
3 types d’encours pourront être retournés dans le cas d’une carte passée en paramètre :
Encours | => montant des facturettes reportées au mois suivant |
Encours terminé non prélevé | => correspond au montant des facturettes du mois courant non encore comptabilisées |
Encours terminé prélevé | => correspond au montant des facturettes du mois précédent |
Un lien self sera également présent 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 et pour un compte à vue ou une carte à débit différé donnés (modulo la pagination éventuelle). 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/accounts/038-CPT30019654051/balances »
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 personas« .
Voir aussi la spécification de place STET V1.4.2.17 / Part III / Section 6.4 / page 9
Résultat
Status code : 200
Body
{ « balances »: [ { « balanceType »: « VALU », « name »: « Solde en Valeur », « balanceAmount »: { « amount »: « 2165.5 », « currency »: « EUR » }, « referenceDate »: « 2020-06-08 » }, { « balanceType »: « CLBD », « name »: « Solde Comptable », « balanceAmount »: { « amount »: « 2165.5 », « currency »: « EUR » }, « referenceDate »: « 2020-06-07 » }, { « balanceType »: « OTHR », « name »: « Solde TP », « balanceAmount »: { « amount »: « 2165.5 », « currency »: « EUR » } } ], « _links »: { « self »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/balances » }, « transactions »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions » }, « parent-list »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » } }}
(cas du persona Marc – D0999990I0)
Codes erreurs
Voici la liste de descriptions des codes erreurs de ce service. Il y a une annotation rouge pour ceux étant définis CFONB.
Lien vers la description de la méthode et des codes retour http
Erreur | Description de l’erreur |
AC01(CFONB) | IncorrectAccountNumber : le numéro de compte est incorrect ou inconnu |
AC04(CFONB) | ClosedAccountNumber : le compte est clos |
AC06(CFONB) | BlockedAccount : le compte est bloqué / fait l’objet d’une opposition |
BE05(CFONB) | UnrecognisedInitiatingParty : l’AISP est inconnu |
BADS | BadScope : l’appel au service a été fait avec un jeton CBPII (AISP attendu) |
INTE | InternalError : il y a une erreur interne de traitement |
INTS | InternalServerError : il y a une erreur interne de communication avec le SI |
IPGN | InvalidPageNumber : le numéro de page est invalide |
NGAC | NotGrantedAccount : le compte n’est pas consenti |
NIMP | NotImplemented : le mauvais verbe est appelé (GET attendu) |
TMRQ | TooManyRequest : le nombre de requêtes possibles a été dépassé |
IPSU | InvalidPSU : Numéro d’abonné non référencé ou abonnement banque à distance résilié |
FF01 | Bad Request : le format de la requête est incorrect |
ENDE | EntriesDateError : format de date incorrectes |
RENF | ReferenceNotFound : mouvement non référencé |
NAAC | NotAvailableAccounts : absence de comptes éligibles |
CDNA | CardNotAvailable ! la carte à débit différé n’est pas ou plus accessible |
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.
Description du test | Jeu de données et Résultat attendu |
Récupération du solde d’un compte
=> Vérification des liens présents dans le résultat de la requête (lien self, soldes et transactions) |
Persona : Marc – 038-CPT30019654051
Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des trois soldes du compte de paiement |
Récupération de tous les soldes d’un compte, les soldes sont à 0
=> Vérification des liens présents dans le résultat de la requête (lien self, soldes et transactions) |
Persona : Adam – 038-CPT30319665741
Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des trois soldes du compte de paiement les soldes sont à 0 |
Récupération des soldes liés à un compte inconnu | Persona : Inconnu – 038-CPT30014684067
Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 404 => compte inconnu message d’erreur : AC01 |
Requête HTTP avec un jeton d’accès non autorisé pour la ressource (scope erroné) | Persona : Marc – 038-CPT30019654051
Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 403 => accès à la ressource refusé message d’erreur : BADS |
Passage d’une requête HTTP POST | Persona : Marc – 038-CPT30019654051
Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 405 => méthode non autorisée |
Obtenir les transactions
Obtenez l’historique des transactions d’un compte à vue ou les facturettes des cartes à débit différé adossées à ce dernier !
Cas d’usage
Ce service permet de récupérer la liste des opérations d’un compte à vue ou la liste des facturettes d’une carte à débit différé du client.
Les transactions obtenues sont inférieures ou égales à 90 jours par rapport à la date du jour.
Une pagination de la liste renvoyée peut être faite s’il y a beaucoup de données à afficher, dans ce cas des liens donnant accès à la première page, la précédente, la suivante et la dernière page faciliteront la consultation des résultats.
Ce service fait suite à la restitution de la liste des comptes à vue et cartes à débit différé d’un client : un resourceId correspondant à un compte ou une carte doit être fourni pour obtenir la liste des transactions.
Les accès à cette méthode sont limités à 4 accès batch maximum par jour calendaire, pour un client et pour un compte / une carte à débit différé donnés, hors pagination.
En résumé, ce service permet de lister les transactions d’un compte à vue du client ou de lister les facturettes d’une carte à débit différé adossée à ce compte à vue.
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 « Vue d’ensemble » > « Récupérer votre jeton« ).
Pour récupérer les transactions d’un compte à vue :
- L’IBAN du compte à vue 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 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 à vue, est récupéré via le résultat de la requête GET /accounts dans la rubrique « resourceId » pour le compte à vue correspondant à cet IBAN, c’est à dire « accountId« : {« iban »: »<IBAN du compte à vue> » }
- 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 à vue
Pour récupérer les transactions d’une carte à débit différé adossée à un compte à vue :
- L’IBAN du compte à vue auquel est adossée la carte à débit différé 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 d’annule et remplace via PUT /consents sans cet IBAN dans la liste « transactions »)
- L « accountResourceId » permettant d’interroger cette méthode pour la carte à débit différé, est récupéré via le résultat de la requête GET /accounts dans la rubrique « resourceId » pour la carte à débit différé, c’est à dire :
- tel que « accountId » : {« other »: {« schemeName » : « CPAN »}}
avec « linkedAccount » qui correspond au « resourceId » du compte à vue - avec le « resourceId » du compte à vue récupéré via la requête GET /accounts et tel que « accountId » : {« iban »: »<IBAN du compte à vue> »}
- tel que « accountId » : {« other »: {« schemeName » : « CPAN »}}
- 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 » de la carte à débit différé
Requête
GET /account/{accoundResourceId}/transactions
Voir aussi la spécification de place STET V1.4.2.17 / Part II / section 4.4 / page 34
Paramètres obligatoires ou facultatifs du body requis pour l’appel de ce service
Paramètres obligatoires : accountResourceId => compte à vue pour lequel on veut consulter les opérations ou carte à débit différé pour laquelle on veut consulter les facturettes.
Paramètres facultatifs :
- 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.
- entryReferenceFrom => référence d’incrément minimum pour l’identifiant technique. Seules les transactions avec une entryReference strictement plus grande que entryReferenceFrom sont restituées
- entryReferenceTo => référence d’incrément maximum pour l’identifiant technique. Seules les transactions avec une entryReference plus petite ou égale que entryReferenceTo sont restituées
- PSU-IP-ADDRESS => à alimenter si le client est connecté
Le format autorisé pour les données dateFrom et dateTo est YYYY-MM-DD.
Résultat retourné
Cet appel permet de récupérer :
- la liste des opérations pour le compte passé en paramètre
- la liste des facturettes de la carte à débit différé passée en paramètre
La date des transactions obtenue est inférieure ou égale à 90 jours par rapport à la date du jour.
Une pagination de la liste renvoyée peut être faite s’il y a beaucoup de données à afficher, dans ce cas des liens de navigation donnant accès à la première page, à la page précédente, à la suivante et à la dernière page, faciliteront la consultation des résultats.
Un lien self sera également présent pour revenir à la page obtenue juste 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 et pour un compte à vue ou une carte à débit différé donnés (modulo la pagination éventuelle). En revanche, lorsque c’est le client connecté qui interroge directement ses comptes à vue, le nombre d’accès n’est pas limité.
BookingDate est reportée dans expectedBookingDate lorsque le mouvement n’est pas comptabilisé (status = « PDNG »)
La remittance information contient un nouvel objet intermédiaire « unstructured »
Suppression du champ « entryReference » lorsqu’il n’est pas renseigné (status = « PDNG »)
Alimentation du champ « bankTransactionCode ».
Les facturettes des cartes à débit différé qui ne sont pas comptabilisées sont au status = « OTHR ».
Précisions sur les types d’opération
Types d’opérations remontés |
Virement émis |
Virement reçu |
Prélèvement émis |
Prélèvement reçu |
Intérêts |
Frais et commissions |
Extourne et rétrocession |
Effets |
Titres et instruments financiers |
Chèques |
Cartes |
Incidents et impayés |
Prêts |
International |
Espèces retrait et versement |
Autres |
Cela se décline dans la sandbox, en 73 libellés de code opération différents pour les 4 500 transactions du persona « SARL UNIPERSONNELLE 2640 » :
Libellé code opération | Type d’opération associé |
ACHAT PARTS BP | Titres et instruments financiers |
ANN VIR SEPA | Virement émis |
ANNU EUROVIR | Virement émis |
ANNUL FRAIS CB | Extourne et rétrocession |
ANNULATION | — |
ANNULATION PRLV | — |
ARRETE DE CPTE | Intérêts |
CASH POOLING | — |
CHEQUE BANQUE | Chèques |
CHEQUE | Chèques |
CHEQUE BANQUE | — |
COM.GESTION DEB | — |
DEBIT DIFFERE | Cartes |
DEPLACE | Chèques |
DEPOT ESPECES | Espèces retrait et versement |
ECH PRET IMPAYE | — |
ECHEANCE PRET | Prêts |
ENVOI EXTRAITS | — |
EUROPRELEVEMENT | Prélèvement reçu |
EUROVIR OCCAS | Virement émis |
EUROVIR PERM | Virement émis |
EUROVIR SEPA | Virement émis |
EUROVIR SEPA | Virement reçu |
EUROVIR SEPA RJ | Autres |
FACT. CB | — |
FACTURE CB | Cartes |
FACTURETTES CB | — |
FRAIS ANNUL EVI | Virement reçu |
FRAIS OU COTIS | Frais et commissions |
FRAIS OU COTIS | — |
FRAIS VIREMENT | Virement émis |
IMP.CARTE BLEUE | Incidents et impayés |
IMPAYE EUROPRLV | Virement reçu |
INTERETS RETARD | International |
LCR DOMICILIEE | Effets |
PRELEVEMENT | Prélèvement reçu |
RAP COMMERCIAL | International |
REGUL.INT.CPTE | — |
REM.CARTE BLEUE | Cartes |
REM.ENCAISSEMEN | Effets |
REMBT EUROPREL | — |
REMBT EUROPREL | Virement reçu |
REMISE EUROPRL | Prélèvement émis |
REMISE EUROPRLV | Prélèvement émis |
REMISES CHEQUES | Chèques |
RETOUR EUROPREL | — |
RETRAIT CAISSE | Espèces retrait et versement |
RETRAIT DISTRIB | Cartes |
RETRAIT UNIQUE | Espèces retrait et versement |
RETRO FR.CHEQUE | — |
REVERSEMEN DCC | — |
REVRST EUROPREL | Virement reçu |
REVRST EUROPRLV | — |
REVRST EUROPRV | — |
TRANSFERT SOLDE | Espèces retrait et versement |
VERST DEPLACE | Espèces retrait et versement |
VERST RAPIDE | Espèces retrait et versement |
VI TRESORERIE | Virement émis |
VI TRESORERIE | Virement reçu |
VIR ADMCP CYBER | Virement émis |
VIR EURO SIMPLE | Virement reçu |
VIR INSTAN EMIS | Virement émis |
VIR INSTAN RECU | Virement émis |
VIR INTERNAT | Prêts |
VIR TRESO CYBER | Virement émis |
VIR.AUTOMATIQUE | Virement émis |
VIREMENT | Virement émis |
VIREMENT | Virement reçu |
VIREMENT CREDIT | Virement reçu |
VIREMENT DEBIT | Virement émis |
VIREMENT EMIS | Virement émis |
VIRT PERMANENT | Virement émis |
La norme STET v1.4.2.17 est appliquée : le champ remittanceInformation que notre API DSP2 renvoie est non structurée (utilisation de la balise « unstructured » contenant un tableau de String).
Exemple
Requête 1
GET /stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions?dateFrom=2019-06-03&dateTo=2019-06-09
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 V1.4.2.17 / Part III / Section 6.5 / page 10
Résultat 1
Status code : 200
Body
{ « _links »: { « balances »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/balances » }, « last »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions?page=last&dateFrom=2020-06-03&dateTo=2020-06-09 » }, « self »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions?dateFrom=2020-06-03&dateTo=2020-06-09 » }, « first »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions?dateFrom=2020-06-03&dateTo=2020-06-09 » }, « parent-list »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » } }, « transactions »: [ { « resourceId »: « 201902000003BD27-4772834 », « remittanceInformation »: { « unstructured »: [ « VIR MALLOW MARC », « remittance info 2 : libelle perso – CRDT – BOOK » ] }, « transactionAmount »: { « amount »: « 145 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « DMCT », « code »: « 078 », « domain »: « PMNT », « family »: « RCDT », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-08 », « valueDate »: « 2020-06-09 », « transactionDate »: « 2020-06-07 », « creditDebitIndicator »: « CRDT », « entryReference »: « 201902000003BD27-4772834 », « status »: « BOOK » }, { « resourceId »: « 201902000003BD27-4772833 », « remittanceInformation »: { « unstructured »: [ « VIR M OMAR JAFFRA », « remittance info 2 : libelle perso – CRDT – BOOK » ] }, « transactionAmount »: { « amount »: « 125 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « DMCT », « code »: « 078 », « domain »: « PMNT », « family »: « RCDT », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-08 », « valueDate »: « 2020-06-09 », « transactionDate »: « 2020-06-07 », « creditDebitIndicator »: « CRDT », « entryReference »: « 201902000003BD27-4772833 », « status »: « BOOK » }, { « resourceId »: « 201902000003BD27-4772832 », « remittanceInformation »: { « unstructured »: [ « PRLV SEPA AIDES », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 12.23 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « OTHR », « code »: « 029 », « domain »: « PMNT », « family »: « RDDT », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-06 », « valueDate »: « 2020-06-07 », « transactionDate »: « 2020-06-05 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201902000003BD27-4772832 », « status »: « BOOK » }, ] }
(cas du persona Marc -D0999990I0)
Requête 2
GET /stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions?dateFrom=2019-06-03&dateTo=2019-06-09
Résultat 2 avec pagination
Status code : 200
Body
{ « _links »: { « next »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30921523550/transactions?page=2 » }, « balances »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30921523550/balances » }, « last »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30921523550/transactions?page=last » }, « self »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30921523550/transactions » }, « first »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30921523550/transactions » }, « parent-list »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » } }, « transactions »: [ { « expectedBookingDate »: « 2020-06-08 », « resourceId »: « 00008BD2B-0000032 », « remittanceInformation »: { « unstructured »: [ « COTIS VISA CLASSIC DI », « remittance info 2 : libelle perso – DBIT – PDNG » ] }, « transactionAmount »: { « amount »: « 17 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 358 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « valueDate »: « 2020-06-08 », « transactionDate »: « 2020-06-09 », « creditDebitIndicator »: « DBIT », « entryReference »: « », « status »: « PDNG » }, { « resourceId »: « 050414320765BD2N-0070232 », « remittanceInformation »: { « unstructured »: [ « ECHEANCE PRET », « remittance info 2 : libelle perso – CRDT – BOOK » ] }, « transactionAmount »: { « amount »: « 0 », « currency »: « EUR » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « CRDT », « entryReference »: « 050414320765BD2N-0070232 », « status »: « BOOK » }, { « resourceId »: « 050414320766BD2N-8242499 », « remittanceInformation »: { « unstructured »: [ « VIR Farago », « remittance info 2 : libelle perso – CRDT – BOOK » ] }, « transactionAmount »: { « amount »: « 265.67 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « DMCT », « code »: « 078 », « domain »: « PMNT », « family »: « RCDT », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « CRDT », « entryReference »: « 050414320766BD2N-8242499 », « status »: « BOOK » }, { « resourceId »: « 201900100001BD27-0000067 », « remittanceInformation »: { « unstructured »: [ « COTIS VISA CLASSIC DI », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 17 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 358 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100001BD27-0000067 », « status »: « BOOK » }, { « resourceId »: « 201900100001BD27-INTSCR », « remittanceInformation »: { « unstructured »: [ « INTS CASH POOL SEP 2019 », « remittance info 2 : libelle perso – CRDT – BOOK » ] }, « transactionAmount »: { « amount »: « 763.96 », « currency »: « EUR » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « CRDT », « 201900100001BD27-INTSCR » « status »: « BOOK » }, { « resourceId »: « 201900100001BD27-LAIZXKL », « remittanceInformation »: { « unstructured »: [ « VIR REJET JOBE SPORTS IN », « remittance info 2 : libelle perso – CRDT – BOOK » ] }, « transactionAmount »: { « amount »: « 336.25 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « ADJT », « code »: « 051 », « domain »: « ACMT », « family »: « MCOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « CRDT », « entryReference »: « 201900100001BD27-LAIZXKL », « status »: « BOOK » }, { « resourceId »: « 201900100001BD27-WHMAT36 », « remittanceInformation »: { « unstructured »: [ « VIR INST ROUSSEAU », « remittance info 2 : libelle perso – CRDT – BOOK » ] }, « transactionAmount »: { « amount »: « 1.00 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « DMCT », « code »: « 078 », « domain »: « PMNT », « family »: « RCDT », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « CRDT », « entryReference »: « 201900100001BD27-WHMAT36 », « status »: « BOOK » }, { « resourceId »: « 201900100002BD27-0000068 », « remittanceInformation »: { « unstructured »: [ « COTIS VISA CLASSIC DI », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 17 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 358 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100002BD27-0000068 », « status »: « BOOK » }, { « resourceId »: « 201900100002BD27-INTSDE », « remittanceInformation »: { « unstructured »: [ « INTS CASH POOL SEP 2019 », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 25.51 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 740 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100002BD27-INTSDE », « status »: « BOOK » }, { « resourceId »: « 201900100003BD27-0000069 », « remittanceInformation »: { « unstructured »: [ « COTIS VISA CLASSIC DI », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 17 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 358 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100003BD27-0000069 », « status »: « BOOK » }, { « resourceId »: « 201900100003BD27-INTSDE », « remittanceInformation »: { « unstructured »: [ « INTS CASH POOL SEP 2019 », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 14.95 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 740 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100003BD27-INTSDE », « status »: « BOOK » }, { « resourceId »: « 201900100004BD27-0000070 », « remittanceInformation »: { « unstructured »: [ « COTIS VISA CLASSIC DI », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 17 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 358 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100004BD27-0000070 », « status »: « BOOK » }, { « resourceId »: « 201900100004BD27-INTSDE », « remittanceInformation »: { « unstructured »: [ « INTS CASH POOL SEP 2019 », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 51.6 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 740 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100004BD27-INTSDE », « status »: « BOOK » }, { « resourceId »: « 201900100005BD27-0000083 », « remittanceInformation »: { « unstructured »: [ « COTIS VISA CLASSIC DI », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 17 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 358 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100005BD27-0000083 », « status »: « BOOK » }, { « resourceId »: « 201900100005BD27-INTSDE », « remittanceInformation »: { « unstructured »: [ « INTS CASH POOL SEP 2019 », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 121.55 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 740 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100005BD27-INTSDE », « status »: « BOOK » }, { « resourceId »: « 201900100006BD27-0000084 », « remittanceInformation »: { « unstructured »: [ « COTIS VISA CLASSIC DI », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 17 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 358 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100006BD27-0000084 », « status »: « BOOK » }, { « resourceId »: « 201900100006BD27-INTSDE », « remittanceInformation »: { « unstructured »: [ « INTS CASH POOL SEP 2019 », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 1.5 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 740 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100006BD27-INTSDE », « status »: « BOOK » }, { « 201900100007BD27-INTSDE », « remittanceInformation »: { « unstructured »: [ « INTS CASH POOL SEP 2019 », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 23.63 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 740 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100007BD27-INTSDE », « status »: « BOOK » }, { « 201900100008BD27-INTSDE », « remittanceInformation »: { « unstructured »: [ « INTS CASH POOL SEP 2019 », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 49.96 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 740 », « domain »: « ACMT » « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 « , « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100008BD27-INTSDE », « status »: « BOOK » }, { « 201900100009BD27-INTSDE », « remittanceInformation »: { « unstructured »: [ « INTS CASH POOL SEP 2019 », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 72.14 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « COMM », « code »: « 740 », « domain »: « ACMT », « family »: « MDOP », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-05 », « valueDate »: « 2020-06-05 », « transactionDate »: « 2020-06-04 », « creditDebitIndicator »: « DBIT », « entryReference »: « 201900100009BD27-INTSDE », « status »: « BOOK » }, ] }
(Cas du persona Sarl Unipersonnelle 2640- D0999995I0)
Requête 3 – Récupération des facturettes d’une carte CB à débit différé
GET /stet/psd2/v1.4.2/accounts/accounts/038-GFCC01w_pPEk8N32abYfHO0xRDlA/transactions
Résultat 3
Status code : 200
Body
{ « transactions »: [ { « resourceId »: « 20190311-18040026653 », « remittanceInformation »: { « unstructured »: [ « VADE AUTOMOBILE 49SAUMUR », « remittance info 2 : libelle perso – DBIT – PDNG » ] }, « transactionAmount »: { « amount »: « 373.86 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « POSD », « code »: « 213 », « domain »: « PMNT », « family »: « CCRD », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-06-30 », « valueDate »: « 2020-06-30 », « transactionDate »: « 2020-06-25 », « creditDebitIndicator »: « DBIT », « entryReference »: « », « status »: « PDNG » }, { « resourceId »: « 20190215-17740020330 », « remittanceInformation »: { « unstructured »: [ « INFOGREFFE CB 94VINCENNES CED », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 3.53 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « POSD », « code »: « 213 », « domain »: « PMNT », « family »: « CCRD », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-05-31 », « valueDate »: « 2020-05-31 », « transactionDate »: « 2020-06-24 », « creditDebitIndicator »: « DBIT », « entryReference »: « 20190215-17740020330 » « status »: « BOOK » }, { « resourceId »: « 20190106-17740020329 », « remittanceInformation »: { « unstructured »: [ « BRICO DEPOT 49SAUMUR 1952 », « remittance info 2 : libelle perso – DBIT – BOOK » ] }, « transactionAmount »: { « amount »: « 66.2 », « currency »: « EUR » }, « bankTransactionCode »: { « subFamily »: « POSD », « code »: « 213 », « domain »: « PMNT », « family »: « CCRD », « issuer »: « SI EQUINOXE – Banque Populaire » }, « bookingDate »: « 2020-05-31 », « valueDate »: « 2020-05-31 », « transactionDate »: « 2020-06-24 », « creditDebitIndicator »: « DBIT », « entryReference »: « 20190106-17740020329 », « status »: « BOOK » }, ], « _links »: { « last »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-GFCC01w_pPEk8N32abYfHO0xRDlA/transactions?page=last » }, « self »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-GFCC01w_pPEk8N32abYfHO0xRDlA/transactions » }, « first »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-GFCC01w_pPEk8N32abYfHO0xRDlA/transactions » }, « parent-list »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts » } } }
(Cas du persona Alix- D0999992I0)
Codes erreurs
Voici la liste de descriptions des codes erreurs de ce service. Il y a une annotation rouge pour ceux étant définis CFONB.
Lien vers la description de la méthode et des codes retour http
Erreur | Description de l’erreur |
AC01 (CFONB) | IncorrectAccountNumber : le numéro de compte est incorrect ou inconnu |
AC04 (CFONB) | ClosedAccountNumber : le compte est clos |
AC06 (CFONB) | BlockedAccount : le compte est bloqué / fait l’objet d’une opposition |
BE05(CFONB) | UnrecognisedInitiatingParty : l’AISP est inconnu |
BADS | BadScope : l’appel au service a été fait avec un jeton CBPII (AISP attendu) |
ENDE | EntriesDatesError : une ou des dates sont erronées |
IPGN | InvalidPageNumber : le numéro de page est invalide |
INTE | InternalError : il y a une erreur interne de traitement |
INTS | InternalServerError : il y a une erreur interne de communication avec le SI |
NGAC | NotGrantedAccount : le compte n’est pas consenti |
NIMP | NotImplemented : le mauvais verbe est appelé (GET attendu) |
TMRQ | TooManyRequest : le nombre de requêtes possibles a été dépassé |
RENF | ReferenceNotFound : la référence de la transaction est inexistante |
IPSU | InvalidPSU : Numéro d’abonné non référencé ou abonnement banque à distance résilié |
FF01 | Bad Request : le format de la requête est incorrect |
NAAC | NotAvailableAccounts : absence de comptes éligibles |
CDNA | CardNotAvailable ! la carte à débit différé n’est pas ou plus accessible |
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.
Description du test | Jeu de données |
Récupération de toutes les transactions d’un compte (sous 90 jours)
=> Vérification des liens présents dans le résultat de la requête (lien self, soldes et transactions) |
Persona :
Alix – 038-CPT30019654081 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions du compte de paiement et de la liste de facturettes de la carte à débit différée |
Récupération des transactions d’un compte et vérification que l’ASPSP gère correctement le mécanisme de pagination
=>Vérification des liens optionnels premier, précédent, suivant, dernier. |
Persona :
Alix – 038-CPT30019654081 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution de la liste paginée des transactions du compte avec trois éléments par page |
Récupération des transactions liées à un compte inconnu | Persona :
Inconnu – CPT310197919611 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 404 => compte inconnu message d’erreur : AC01 |
Requête HTTP avec un jeton d’accès non autorisé pour la ressource (scope erroné, par exemple « extended_transaction_history » qui n’est pas géré par les Banques Populaires) | Persona :
Marc – 038-CPT30019654051 Prérequis : scope OAuth2 <> aisp Résultat : réponse HTTP 403 => accès à la ressource refusé message d’erreur : BADS |
Passage d’une requête HTTP POST | Persona :
Marc – 038-CPT30019654051 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 405 => méthode non autorisée |
Récupérer la liste des transactions en précisant une date de début
=>Vérification que le filtre est bien appliqué |
Persona :
Alix – 038-CPT30019654081 dateFrom : mettre « la date du jour – 8 jours » Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ultérieures à la date donnée en entrée |
Récupérer la liste des transactions en précisant une date de fin
=>Vérification que le filtre est bien appliqué |
Persona :
Alix – 038-CPT30019654081 dateTo : mettre « la date du jour – 1 jour » Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions antérieures à la date donnée en entrée dans la limite des 90 jours d’ancienneté |
Récupérer la liste des transactions en précisant une référence d’incrément minimum pour l’identifiant technique
=>Vérification que le filtre est bien appliqué |
Persona :
Alix – 038-CPT30019654081 afterEntryReference : 3 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ayant un incrément supérieur à celui donné en entrée |
Récupérer la liste des transactions en précisant une date de début et une date de fin
=>Vérification que le filtre est bien appliqué |
Persona :
Alix – 038-CPT30019654081 dateFrom : mettre « la date du jour – 8 jours » dateTo : mettre « la date du jour – 2 jours » Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions comprises entre la date de début et la date de fin |
Récupérer la liste des transactions en précisant une date de début et une référence d’incrément minimum pour l’identifiant technique
=>Vérification que le filtre est bien appliqué |
Persona :
Alix – 038-CPT30019654081 dateFrom : mettre « la date du jour – 8 jours » afterEntryReference : 2 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ayant un incrément supérieur à celui donné en entrée et une date supérieure à celle donnée en entrée |
Récupérer la liste des transactions en précisant une date de fin et une référence d’incrément minimum pour l’identifiant technique
=>Vérification que le filtre est bien appliqué |
Persona :
Alix – 038-CPT30019654081 dateTo : mettre « la date du jour – 2 jours » afterEntryReference : 2 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ayant un incrément supérieur à celui donné en entrée et une date inférieure à celle donnée en entrée |
Récupérer la liste des transactions en précisant une date de début et de fin ainsi qu’une référence d’incrément minimum pour l’identifiant technique
=>Vérification que le filtre est bien appliqué |
Persona :
Alix – 038-CPT30019654081 dateFrom : mettre « la date du jour – 8 jours » dateTo : mettre « la date du jour – 2 jours » afterEntryReference : 2 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ayant un incrément supérieur à celui donné en entrée et une date comprise entre celles données en entrée |
Passage d’une requête pour avec une période de transactions demandée supérieure à 90 jours | Persona :
Alix – 038-CPT30019654081 dateFrom : mettre « la date du jour – 92 jours Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 400 => requête erronée, période non autorisée message d’erreur : ENDE |
Passage d’une requête de récupération des transactions avec une date au format incorrect | Persona :
Alix – 038-CPT30019654081 dateFrom : mettre une date au format incorrect Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 400 => requête erronée message d’erreur : ENDE |
Passage d’une requête de récupération des transactions avec plus de 200 transactions en résultat
=> Vérifier qu’il y ait bien 200 transactions sur la première page (pagination) |
Persona :
Adam – 038-CPT30319665742 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK 245 transactions sont retournées sur deux pages avec une profondeur d’historique de trois mois |
Passage de requêtes de récupération des transactions avec 4 500 transactions en résultat en tout pour 5 comptes et une carte à débit différé.
73 typologies / codes opérations différents sont restitués. => Vérifier qu’il y ait bien 200 transactions sur la première page (pagination) lorsque plus de 200 transactions sont récupérées |
Persona :
SARL UNIPERSONNELLE 2640
Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK |
Obtenir les bénéficiaires de confiance
Cas d’usage
Ce cas d’usage décrit la méthode GET /trustedBeneficiaries que la norme DSP2 prévoit pour récupérer la liste des bénéficiaires de confiance d’un client qui vous a donné son consentement pour le faire.
Cette méthode n’est pas disponible car la notion de bénéficiaires de confiance n’est pas supportée par notre Système d’Information. L’appel à cette requête renverra un code HTTP 501.
Obtenir l'identité du client
Cas d’usage
Ce service permet de récupérer l’identité d’un client qui vous a donné son consentement pour le faire.
Les accès à cette méthode sont limités à 4 accès batch maximum par jour calendaire, pour un PSU donné.
En résumé, ce service permet de récupérer l’identité du PSU.
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 « Vue d’ensemble » > « 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 V1.4.2.17 / Part II / section 4.6.4 / page 43
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 V1.4.2.17 / Part III / Section 6.3 / page 8
Résultat
Status code : 200
Body
{
« connectedPsuNamePrefix »: « MIST »,
« connectedPsu »: « MALLOW MARC »,
« connectedPsuFirstName »: « Marc »,
« connectedPsuLastName »: « MALLOW »,
« _links »: {
« self »: {
« href »: « .sandbox.api.89C3.com/stet/psd2/v1.4.2/end-user-identity » >https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/end-user-identity »
},
« parent-list »: {
« href »: « .sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts » >https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts »
}
}
}
(cas du persona Marc – D0999990I0)
Codes erreurs
Voici la liste de descriptions des codes erreurs de ce service. Il y a une annotation pour ceux étant définis CFONB.
Lien vers la description de la méthode et des codes retour http
Erreur | Description de l’erreur |
BE05(CFONB) | UnrecognisedInitiatingParty : l’AISP est inconnu |
BADS | BadScope : l’appel au service a été fait avec un jeton CBPII (AISP attendu) |
INTE | InternalError : il y a une erreur interne de traitement |
INTS | InternalServerError : il y a une erreur interne de communication avec le SI |
NIMP | NotImplemented : le mauvais verbe est appelé (GET attendu) |
IPSU | InvalidPSU : Numéro d’abonné non référencé ou abonnement banque à distance résilié |
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.
Description du test | Jeu de données |
Récupération de l’identité de l’utilisateur | Persona :
Marc – D0999990I0 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK |
Récupération de l’identité de l’utilisateur qui n’a pas donné son consentement pour cela | Persona :
Tech’n Co – D0999993I0 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 403 => accès à la ressource refusé |
Console Try-it
Principe
En vous connectant sur le portail BPCE API, vous pouvez :
- faire appel à l’API « Information sur compte » via un formulaire dans lequel vous sélectionnez votre application et le jeton d’authentification/d’accès
- puis vous saisissez les paramètres de la méthode que vous souhaitez tester (soit header, soit body) dont ceux mentionnés par une étoile sont obligatoires
Une fois les paramètres saisis, vous pouvez lancer l’exécution de la requête : vous obtiendrez soit un résultat, soit une erreur.
Pour les méthodes GET /accounts/transactions et GET /accounts/balances, vous devez d’abord exécuter la requête GET /accounts pour récupérer la liste des comptes à vue et des cartes à débit différé adossées à ces comptes à vue. Cela vous permet de récupérer le « ressourceId » nécessaire pour passer ces méthodes pour le compte à vue ou la carte à débit différé.
Les données utilisées pour faire le test en Try-It sont issues des personas (voir la rubrique « Comment tester l’API ? » > « Tester nos personas« ).
L’utilisateur peut choisir un profil spécifique de client pour son test de façon à mieux appréhender les résultats obtenus.
En cas de nécessité, une pagination des résultats sera faite pour faciliter la lisibilité et des liens de navigation entre les différentes pages de résultats seront présents (voir les exemples présents dans les cas d’usage « Obtenir la liste des comptes » et « Obtenir les transactions« ).
Création d’une application de test
La création d’une application de test qui utilise l’API stetpsd2v142 sur le portail BPCE API est un prérequis à l’utilisation de la console « Try-It » pour tester des appels à notre API Information sur compte pour la version v1.4.2 de la norme STET
Si vous avez déjà effectué une demande de GoLive, vous devez alors créer une nouvelle application, puis sélectionner la nouvelle API STET V1.4.2.
Si vous n’avez PAS effectué de demande de GoLive, vous pouvez :
- soit modifier votre application existante pour l’associer à la nouvelle API STET V1.4.2.
- soit créer une nouvelle application, puis sélectionner la nouvelle API STET V1.4.2.
Il faut avoir renseigné les identifiants OAuth avec :
- Type d’application : Public
- « * » dans le champ « Origines Javascript »
- Une URL syntaxiquement valide dans le champ « Rediriger les URL ». Par exemple : « https://monappli.com »
- Ne rien mettre dans le champ Certificat X.509 (juste un caractère « 1 » par exemple)
L’onglet « clients de test » permet de voir les identifiants des personas qui seront sélectionnables dans la console Try-It.
Aperçu de l’écran permettant de récupérer le jeton Oauth2
Cet écran est accessible lorsque l’on édite l’application (DSP2 dans notre cas) et il permet de générer ou éditer un jeton OAuth2 que l’on sélectionnera dans le formulaire d’exécution Try-It.
Aperçu du formulaire d’exécution du Try-It
La console Try-It est disponible en haut à droite des pages présentant les opérations disponibles sur une API. Par exemple, pour l’API Consultation de compte STET v1.4.2, si l’on sélectionne une opération dans le menu sous le bloc STETPSD2V142, la description de l’opération (issu du fichier swagger sous-jacent) est présentée et on peut accéder à la console Try-It pour tester cette opération.
Cliquer sur le bouton Exécuter.
!–
Paramètres du Try-It pour chacune des méthodes de l’API « Information sur compte »
Nb : pour les paramètres de type de données « body », il est possible de copier-coller les exemples (partie gauche de l’écran) dans le formulaire (à droite de l’écran) en changeant juste les valeurs spécifiques au client choisi.
Paramètres communs à toutes les méthodes de l’API « Information sur compte »
Paramètre | Description | Type de données | Type de paramètre | Obligatoire |
Authorization | Jeton d’accès devant être fourni comme header.
Note : en fait, dans la console Try-It, le renseignement de ce paramètre en header est caché et implicite. La valeur envoyée dépend du choix de la combobox « Client OAuth » |
Chaîne de caractères | Header | Oui |
PSU-IP-Address | Adresse IP utilisés par le client connecté sur votre application
*obligatoire si le client est connecté mais non renseignée en cas d’accès batch |
Chaîne de caractères | Header | Non* |
PSU-IP-Port | Port IP du terminal utilisé par le client connecté sur votre APP | Chaîne de caractères | Header | Non |
PSU-HTTP-Method | Méthode http utilisée pour la requête du client | Chaîne de caractères | Header | Non |
PSU-Date | Timestamp utilisé par la requête du client | Chaîne de caractères | Header | Non |
PSU-GEO-Location | Localisation géographique que le client vous a fournie via son terminal si elle est disponible | Chaîne de caractères | Header | Non |
PSU-User-Agent | Header « User-Agent » envoyé par le terminal du client connecté à votre APP | Chaîne de caractères | Header | Non |
PSU-Referer | Header « Referer » envoyée par le terminal du client connecté à votre APP. Il est à noter que dans des spécifications antérieures des RFC 1945 on préconise le nom « referer » (mal orthographié). Le nom « referrer » peut être utilisé au risque de ne pas être compris. | Chaîne de caractères | Header | Non |
PSU-Accept | Header « Accept » envoyé par le terminal du client connecté à votre APP. | Chaîne de caractères | Header | Non |
PSU-Accept-Charset | Header « Accept-Charset » envoyé par le terminal du client connecté à votre APP. | Chaîne de caractères | Header | Non |
PSU-Accept-Encoding | Header « Accept-Encoding » envoyé par le terminal du client connecté à votre APP. | Chaîne de caractères | Header | Non |
PSU-Accept-Language | Header « Accept-Language » envoyé par le terminal du client connecté à votre APP. | Chaîne de caractères | Header | Non |
PSU-Device-ID | UUID (Identifiant Unique Universel) pour un périphérique utilisé par le client, s’il est disponible. L’UUID identifie un périphérique ou l’installation d’une application dépendante d’un périphérique. Dans le cas d’une identification d’installation cet ID nécessite d’être persistant jusqu’au retrait du périphérique. | Chaîne de caractères | Header | Non |
Digest | Synthèse du body | Chaîne de caractères | Header | Non |
Signature | Signature http de la requête (voir https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) La partie keyId du header devrait avoir le format suivant keiId= »SN=XXX,CA=YYYYYYYYYYYYYYYY » où « XXX » est le numéro de série en hexadécimal sans aucun préfixe (comme 0x, du certificat QSEAL dont la clé privée a servi pour la signature de celui-ci
« YYYYYYYYYYYYYYYY » est l’émetteur DN, nom complet de l’autorité de certification ayant émise ce certificat HTTP400 qui sera renvoyé par le serveur dans le cas d’une signature invalide ou absente. |
Chaîne de caractères | Header | Oui |
X-Request-ID | Header de corrélation à paramétrer dans la requête et devant être récupéré dans la réponse à celle-ci | Chaîne de caractères | Header | Oui |
Paramètre propre à la méthode « Obtenir les soldes d’un compte à vue ou les encours des cartes à débit différé adossées à ce dernier » –
get/accounts/{}/balances
Paramètre | Description | Type de données | Type de paramètre | Obligatoire |
accountResourceId | Identification de la ressource utilisée comme critère principal dans la requête. Il est récupéré via le résultat de la requête « GET /accounts » dans la rubrique « ressourceId » :
|
Chaîne de caractères | Chemin | Oui |
Paramètres propres à la méthode « Obtenir les transactions d’un compte à vue ou les facturettes des cartes à débit différé adossées à ce dernier » – GET /accounts/{}/transactions
Paramètre | Description | Type de données | Type de paramètre | Obligatoire |
accountResourceId | Identification de la ressource utilisée comme critère principal dans la requête. Il est récupéré via le résultat de la requête « GET /accounts » dans la rubrique « ressourceId » :
|
Chaîne de caractères | Chemin | Oui |
dateTo | Date inclusive minimale d’imputation des transactions. Les transactions ayant une date d’imputation égale à ce paramètre sont inclues dans le résultat de la requête | Chaîne de caractères | Requête | Non |
dateFrom | Date exclusive maximale d’imputation des transactions. Les transactions ayant une date d’imputation égale à ce paramètre sont exclues du résultat de la requête | Chaîne de caractères | Requête | Non |
afterEntryReference | Ce paramètre fournit la valeur du critère qui déterminera le résultat de la requête. Seules les transactions ayant un identifiant technique supérieur à la valeur fournie seront inclues dans le résultat | Chaîne de caractères | Requête | Non |
Assamblage sandbox
Introduction – précisions sur les fonctionnalités de la sandbox
La sandbox BPCE API peut être utilisée de 2 manières :
- Soit via le Try-it du portail BPCE-API (voir la rubrique « Comment tester l’API ? » > « Console Try-it« ).
- Soit directement via votre application : c’est le mode assemblage décrit ci-après.
En assemblage sandbox, il y a 2 appels :
- Le premier pour identifier/authentifier le client, puis récupérer le jeton d’autorisation (voir la rubrique « Vue d’ensemble » > « Récupérez votre jeton« ) ou le rafraîchir (voir la rubrique « Vue d’ensemble » > « Rafraîchissez votre jeton« ).
- Le second pour faire l’appel à l’API « Information sur compte » (voir les cas d’usage « Obtenir la liste des comptes« , « Transmettre la liste des comptes« , « Obtenir les soldes« , « Obtenir les transactions« , « Obtenir les bénéficiaires de confiance » et « >Obtenir l’identité du client« )
Votre application consommatrice de l’API « Information sur compte » en assemblage sandbox va devoir récupérer un jeton d’accès via sa clé d’authentification auprès de l’AS (Authentification Server).
Ainsi votre application pourra consommer les méthodes GET /accounts, PUT /consents, GET /accounts/{accountResourceId}/transactions, GET /accounts/{accountResourceId}/balances, GET /trusted-beneficiaries et GET /end-user-identity grâce à son jeton d’accès.
Les appels des méthodes de l’API pourront être enchaînés :
- En exécutant la requête de récupération de la liste des comptes à vue GET /accounts dans un premier temps ;
- Puis, en exécutant la requête de transmission des consentements donnés par le client PUT /consents;
- Ensuite, en exécutant la requête de récupération du solde GET /accounts/{accountResourceId}/balances, en passant en paramètre le « resourceId » d’un des comptes récupérés du résultat de la première requête. Idem avec la requête de récupération de l’historique des transactions du compte GET /accounts/{accountResourceId}/transactions ;
- Puis, en exécutant la requête de récupération de la liste des bénéficiaires de confiance du client GET /trusted-beneficiaries
=> cette méthode renvoie systématiquement une erreur car la notion de bénéficiaires n’est pas supportée par notre Système d’Information. - Enfin, en exécutant la requête de récupération de l’identité du client GET /end-user-identity
Les données utilisées pour faire les tests seront issues des persona (voir la rubrique « Comment tester l’API ? » > « Testez nos persona« ), ce qui permettra de choisir des profils spécifiques selon les tests de façon à mieux appréhender les résultats obtenus.
En cas de nécessité, une pagination des résultats sera faite pour faciliter la lisibilité et des liens de navigation entre les différentes pages de résultats seront présents (voir les exemples présents dans les cas d’usage « Gérez le consentement » et « Obtenez les transactions« ), ce qui implique que l’application consommatrice puisse gérer correctement cette pagination.
Prérequis
Pour consommer nos API en sandbox, vous devez déclarer votre APP sur le portail BPCE API (cf. menu « Mes applications« ) et nous transmettre les clés publiques de vos certificats QWAC et QEALC de test afin que nous puissions :
- Déclarer votre APP comme application consommatrice de l’API ;
- Intégrer vos clés publiques QWAC et QSEALC de test dans nos infrastructures ;
- Récupérer et contrôler votre organizationId et votre rôle « AISP » dans notre registre des TPP ;
- Utiliser votre URI de redirection (callback) qui sera appelée par l’ASPSP ;
- si le client 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)
Pour consommer nos API en live, vous devez déclarer votre APP
- Soit lors du processus de « GO Live » via notre portail BPCE API (ancienne procédure);
- Soit via l’API register (procédure actuelle), (cf : https://www.api.89c3.com/fr/nos-produits/item/522-api-register-fr)
Rappel : en tant que TPP, vous devez être accrédité (ou en cours d’accréditation) par l’une des autorités compétentes nationales européennes (ACPR en France) pour le rôle d’agrégateur de compte (« AISP »).
Enchaînement des étapes pour tester l’accès à l’API AISP depuis votre APP
1ère étape : Faire la demande de jeton via la redirection
Cet appel vous permet de déclencher l’identification du client dans l’établissement qui détient ses comptes, prérequis à l’obtention d’un jeton d’accès pour cet établissement. Il s’agit de demander au client connecté de donner son contentement pour accéder à ses données pendant 180 jours
La description de la fonctionnalité est décrite dans la rubrique « Vue d’ensemble » > « Récupérez votre jeton« .
NB : Le client pouvant domicilier ses comptes dans plusieurs banques du Groupe BPCE, il vous faudra un jeton différent pour accéder à chacune de nos banques si le client souhaite agréger ses comptes depuis chacune d’entre elles => cet appel et les appels suivants seront donc à répéter pour chacun des établissements concernés.
Afin de pouvoir interroger le bon backend, dans le parcours client, il est donc nécessaire que vous prévoyiez d’interroger le client au préalable sur son(ses) établissement(s) de rattachement.
Pour l’accès à l’assemblage sandbox, le point d’entrée dépend du code établissement : « www.<cdetab>.sandbox.api.89C3.com ».
Les seuls établissements bancaires utilisables en assemblage sandbox pour cette API sont les suivants (code établissement <cdetab> utilisé dans les URL) :
Code établissement | Nom de l’établissement | Nom abrégé |
13807 | B.P Grand Ouest | BPGO |
13807 | CMM Grand Ouest | CMMGO |
Requête de redirection vers la page d’identification :
GET https://www.13807.sandbox.api.89C3.com/stet/psd2/oauth/authorize
Headers :
Content-Type:application/x-www-form-urlencoded; charset=utf-8
Params :
redirect_uri : https://myAPP.fr/Home/OAuth2Callback
client_id : PSDFR-ACPR-13807
response_type : code
scope : AISP
Remarques sur l’alimentation des champs :
client_id :
- Si l’enregistrement du TPP a été réalisé au travers du processus de « GO Live » via notre portail BPCE API (ancienne procédure)
- numéro d’agrément donné par votre autorité compétente (PSDXX-YYYYYYYY-ZZZZZZZZ)
- Ou si l’enregistrement du TPP a été réalisé via l’API register (procédure actuelle)
- client_id retourné dans la réponse au POST /register
redirect_uri : URL de redirection prédéclarée dans votre application consommatriceETà communiquer à l’ASPSP
- lors de l’étape GO Assemblage (resp. GO Live en production) si le TPP a été enregistré par la procédure actuelle ;
- à l’API register si le TPP s’est enregistré par la procédure automatisée.
2ème étape : La redirection vers les écrans
Cinématique nominale des enchaînements des écrans d’identification et d’authentification forte :
Déroulé de l’enchaînement des écrans d’identification et d’authentification forte :
1) Le client est redirigé vers un écran d’identification proposé par son établissement bancaire et dans lequel il saisira son identifiant de banque à distance.
L’identifiant de banque à distance du client est à saisir (voir la rubrique « Comment tester l’API ? » > « Tester nos personas » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires :
2) Le client est redirigé vers un écran d’authentification forte proposé par son établissement bancaire pour valider son identité.
Le code SMS pour authentification est à saisir (voir la rubrique « Comment tester l’API ? » > « Testez nos personas » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires :
La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du client par l’établissement bancaire (SMS OTP, secur’pass, etc.).
Elle dépend aussi de l’équipement du client sur lequel tourne l’APP de l’AISP utilisée par le client (PC ou mobile/tablette).
Dans certains cas, une notification peut être envoyée vers le client afin qu’il active son moyen d’authentification forte, et pour terminer cette étape.
3ème étape : Récupérer un jeton d’accès / access_token
Vous devez fournir votre certificat QWAC dans la requête POST /stet/psd2/oauth/token pour que l’infrastructure d’API de l’ASPSP puisse faire les vérifications liées à votre profil et vérifier votre identité.
Le certificat doit correspondre à celui-ci que le PSP a fourni :
- lors de l’étape GO Assemblage (resp. GO Live en production) si le TPP a été enregistré par la procédure manuelle,
- à l’API register si le TPP s’est enregistré par la procédure automatisée.
Cet appel permet à l’AISP de récupérer le jeton pour pouvoir accéder aux données à partir de l’URL de callback enregistrée par l’AISP dans son application consommatrice.
Si le client vous a autorisé à récupérer ses données pour un établissement, vous trouverez dans la réponse à l’appel précédent, le code à utilisation unique qui permet de récupérer un access_token.
Cet access_token est valable 1h et est un prérequis pour chaque accès à l’une des méthodes de l’API d’information sur compte. La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Récupérer votre jeton« .
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 cinématique « Rafraîchir votre acces_token » ci-après.
Au bout de 180 jours votre refresh_token arrive à expiration. Pour en récupérer un nouveau, vous devez reprendre la cinématique « Récupérer un jeton d’accès » et passer par une nouvelle étape d’authentification forte du client auprès de l’établissement bancaire.
Requête:
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/oauth/token
Headers :
Content-Type:application/x-www-form-urlencoded; charset=utf-8
Params :
redirect_uri:
client_id:PSDFR-ACPR-13807
grant_type:authorization_code
code:NnZx1hqHY2CLkCFjiTwhJeflgNnCrB
Remarques sur l’alimentation des champs :
client_id :
- Si l’enregistrement du TPP a été réalisé au travers du processus de « GO Live » via notre portail BPCE API (ancienne procédure)
- numéro d’agrément donné par votre autorité compétente (PSDXX-YYYYYYYY-ZZZZZZZZ)
- Ou si l’enregistrement du TPP a été réalisé via l’API register (procédure actuelle)
- client_id retourné dans la réponse au POST /register
Code : récupéré dans l’url de callback
redirect_uri : URL de redirection prédéclarée dans votre application consommatrice
ET à communiquer à l’ASPSP
- lors de l’étape GO Assemblage (resp. GO Live en production) si le TPP a été enregistré par la procédure actuelle ;
- à l’API register si le TPP s’est enregistré par la procédure automatisée.
Il faut que la redirect_uri soit la même que pour la requête GET /authorize
Réponse :
{
« access_token »: « KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAs6iLw »,
« token_type »: « Bearer »,
« expires_in »: 3600,
« scope »: « aisp offline_access »,
« refresh_token »: « KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAs6iLa »
}
4ème étape : Consommer les méthodes de l’API
- Obtenir la liste des comptes à vue et cartes à débit différé d’un client
Cet appel vous permet de lister les comptes du client connecté ou non.
La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Lister les comptes« .
Exemple de requête de récupération de la liste des comptes en assemblage sandbox :
Requête :
GET https://www.13807.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts
Headers :
Authorization:Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAs6iLw
Signature : keyId=\ »MZGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB\ »,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+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\
X-request-id:id-1234567890111121 1
Psu-Ip-Address:192.168.0.1
Remarques sur l’alimentation des champs :
Authorization:Bearer => access_token récupéré pour le token
Psu-Ip-Address => permet de différencier les appels batch et les appels avec le client connecté : ce champ est à alimenter pour un client connecté
Réponse :
200 OK
Headers :
X-request-id:id-1234567890111121 1
Remarques sur l’alimentation des champs :
X-request-id: transmis en entrée
Body :
{
« _links »: {
« last »: {
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts?page=last »
},
« self »: {
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts »
},
« first »: {
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts »
}
},
« accounts »: [
{
« cashAccountType »: « CACC »,
« accountId »: {
« iban »: « FR7613807008043001965409135 »,
« currency »: « EUR »
},
« resourceId »: « 038-CPT30019654091 »,
« product »: « COMPTE COURANT »,
« _links »: {},
« usage »: « ORGA »,
« psuStatus »: « Account Holder »,
« name »: « Tech-N Co »,
« bicFi »: « CCBPFRPPNAN »,
« details »: « COMPTE COURANT »
}
]
}
(cas du persona Tech-N Co – D0999993I0 pour lequel aucun consentement n’a été donné via la méthode PUT /consents)
{
« _links »: {
« last »: {
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts?page=last »
},
« self »: {
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts »
},
« first »: {
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts »
},
« endUserIdentity »: {
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/end-user-identity »
}
},
« accounts »: [
{
« cashAccountType »: « CACC »,
« accountId »: {
« iban »: « FR7613807008043001965405158 »,
« currency »: « EUR »
},
« resourceId »: « 038-CPT30019654051 »,
« product »: « COMPTE CHEQUE »,
« balances »: [
{
« balanceType »: « VALU »,
« name »: « Solde en Valeur »,
« balanceAmount »: {
« amount »: « 4321.95 »,
« currency »: « EUR »
},
« referenceDate »: « 2020-06-12 »
},
{
« balanceType »: « CLBD »,
« name »: « Solde Comptable »,
« balanceAmount »: {
« amount »: « 4179.95 »,
« currency »: « EUR »
},
« referenceDate »: « 2020-06-11 »
},
{
« balanceType »: « OTHR »,
« name »: « Solde TP »,
« balanceAmount »: {
« amount »: « 4348.95 »,
« currency »: « EUR »
}
}
],
« _links »: {
« balances »: {
« templated »: false,
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/balances »
},
« transactions »: {
« templated »: false,
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions »
}
},
« usage »: « PRIV »,
« psuStatus »: « Account Holder »,
« name »: « Compte perso »,
« bicFi »: « CCBPFRPPNAN »,
« details »: « COMPTE CHEQUE »
},
{
« cashAccountType »: « CACC »,
« accountId »: {
« iban »: « FR7613807008043001965405255 »,
« currency »: « EUR »
},
« resourceId »: « 038-CPT30019654052 »,
« product »: « COMPTE CHEQUE »,
« balances »: [
{
« balanceType »: « VALU »,
« name »: « Solde en Valeur »,
« balanceAmount »: {
« amount »: « 459.56 »,
« currency »: « EUR »
},
« referenceDate »: « 2020-06-12 »
},
{
« balanceType »: « CLBD »,
« name »: « Solde Comptable »,
« balanceAmount »: {
« amount »: « 459.56 »,
« currency »: « EUR »
},
« referenceDate »: « 2020-06-11 »
},
{
« balanceType »: « OTHR »,
« name »: « Solde TP »,
« balanceAmount »: {
« amount »: « 459.56 »,
« currency »: « EUR »
}
}
],
« _links »: {
« balances »: {
« templated »: false,
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654052/balances »
},
« transactions »: {
« templated »: false,
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654052/transactions »
}
},
« usage »: « PRIV »,
« psuStatus »: « Account Holder »,
« name »: « Retrait et Cheques »,
« bicFi »: « CCBPFRPPNAN »,
« details »: « COMPTE CHEQUE »
},
{
« cashAccountType »: « CACC »,
« accountId »: {
« iban »: « FR7613807008043001965405352 »,
« currency »: « EUR »
},
« resourceId »: « 038-CPT30019654053 »,
« product »: « COMPTE CHEQUE »,
« balances »: [
{
« balanceType »: « VALU »,
« name »: « Solde en Valeur »,
« balanceAmount »: {
« amount »: « 2165.5 »,
« currency »: « EUR »
},
« referenceDate »: « 2020-06-12 »
},
{
« balanceType »: « CLBD »,
« name »: « Solde Comptable »,
« balanceAmount »: {
« amount »: « 2165.5 »,
« currency »: « EUR »
},
« referenceDate »: « 2020-06-11 »
},
{
« balanceType »: « OTHR »,
« name »: « Solde TP »,
« balanceAmount »: {
« amount »: « 2165.5 »,
« currency »: « EUR »
}
}
],
« _links »: {
« balances »: {
« templated »: false,
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654053/balances »
},
« transactions »: {
« templated »: false,
« href »: « https://www.<cdetab>.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654053/transactions »
}
},
« usage »: « PRIV »,
« psuStatus »: « Account Holder »,
« name »: « Compte mensualités »,
« bicFi »: « CCBPFRPPNAN »,
« details »: « COMPTE CHEQUE »
}
]
}
- Transmettre la liste des comptes à vue consentis par le client pour la consultation des soldes et/ou des transactions
Même principe de passage du jeton d’accès qu’au paragraphe « Obtenir la liste des comptes à vue et cartes à débit différé d’un client » ci-dessus.
Un exemple est donné dans le cas d’usage « Gérer le consentement« .
Requête :
PUT https://www.13807.sandbox.api.89C3.com/stet/psd2/v1.4.2/consents
Headers :
Content-Type : application/json
Authorization : Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAs6iLw
Signature : keyId=\ »MZGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB\ »,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+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\
X-request-id:id-1234567890111121 2
Psu-Ip-Address : 192.168.0.1
Remarques sur l’alimentation des champs :
Authorization:Bearer => access_token récupéré pour le token
Psu-Ip-Address => permet de différencier les appels batch et les appels avec le client connecté : ce champ est à alimenter pour un client connecté
Body (avec un IBAN de l’abonné) :
{
« balances »: [
{
« iban »: « FR7613807008043001965405158 »
}
],
« transactions »: [
{
« iban »: « FR7613807008043001965405158 »
}
],
« trustedBeneficiaries »: true,
« psuIdentity »: true
}
Réponse :
Headers :
X-request-id:id-1234567890111121 2
Remarques sur l’alimentation des champs :
X-request-id: transmis en entrée
Pas de body mais un « 201 – Created »
- Obtenir les soldes d’un compte à vue ou les encours des cartes à débit différé adossées à ce dernier
Même principe de passage du jeton d’accès qu’au paragraphe « Obtenir la liste des comptes à vue et cartes à débit différé d’un client » ci-dessus.
La description de la méthode et un exemple sont donnés dans le cas d’usage « Obtenir les soldes« .
- Obtenir les transactions d’un compte à vue ou les facturettes des cartes à débit différé adossées à ce dernier
Même principe de passage du jeton d’accès qu’au paragraphe « Obtenir la liste des comptes à vue et cartes à débit différé d’un client » ci-dessus.
La description de la méthode et un exemple sont donnés dans le cas d’usage « Obtenir les transactions« .
- Obtenir la liste des bénéficiaires de confiance d’un client => ce service sera disponible au dernier trimestre 2019.
Même principe de passage du jeton d’accès qu’au paragraphe « Obtenir la liste des comptes à vue et cartes à débit différé d’un PSU » ci-dessus.
La description de la méthode et un exemple seront donnés dans le cas d’usage « Obtenir les bénéficiaires de confiance » => ce service n’est pas implémenté.
- Obtenir l’identité du client
Même principe de passage du jeton d’accès qu’au paragraphe « Obtenir la liste des comptes à vue et cartes à débit différé d’un client » ci-dessus.
La description de la méthode et un exemple seront donnés dans le cas d’usage « Obtenir l’identité du client« .
- Rafraîchir le jeton d’accès avec le refresh_token
Requête:
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/oauth/token
Headers :
Content-Type:application/x-www-form-urlencoded; charset=utf-8
Données dans le body de la requête POST
client_id:PSDFR-ACPR-13807
grant_type:refresh_token
refresh_token:KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAs6iLa
Remarques sur l’alimentation des champs :
client_id :
- Si l’enregistrement du TPP a été réalisé au travers du processus de « GO Live » via notre portail BPCE API (ancienne procédure)
- numéro d’agrément donné par votre autorité compétente (PSDXX-YYYYYYYY-ZZZZZZZZ)
- Ou si l’enregistrement du TPP a été réalisé via l’API register (procédure actuelle)
- client_id retourné dans la réponse au POST /register
Réponse :
{
« access_token »: « 4s2Bt3MRL7nlPUZcRTPe5Tjs0v8p7ZOXOyEKs1juYesj9pPaU7hXFA »,
« token_type »: « Bearer »,
« expires_in »: 3600,
« scope »: « aisp offline_access »,
« refresh_token »: « KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAs6iLa »
}
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.
Cette page présente les jeux de données qui permettent de tester l’API :
- Des clients fictifs sont proposés par segment de clientèle (étudiant, cadre, entreprise, etc.) qui recouvrent des cas de clients PART, PRO et ENT :
- 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 de personnalité 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.
- Les catégories « professionnel » (PRO) et « entreprise » (ENT) couvrent les personnes morales.
- Les caractéristiques de leurs comptes et cartes à débit différé y sont déclinées (mono-compte, multi-comptes, multi-bancarisé, présence d’une carte à débit différé, solde du compte)
- Les données utiles attendues en entrée par les API y sont énumérées (identifiant banque à distance, code SMS pour les authentifications fortes, IBAN).
Les identifiants et données ci-dessous sont des données fictives et ne peuvent pas être utilisées en production.
Persona | Segment | Identifiant banque à distance | Code SMS pour authentification | Code établissement | IBAN | Numéro de compteaccountId | Compte à vue | Soldebalance | Devisecurrency | Transactions consenties ? | Soldes consentis ? |
Marc | Cadre
(PART) |
D0999990I0 | 12345678 | 13807 | FR7613807008043001965405158 | 038-CPT30019654051 | A vue | 4 179.00 | EUR | OK | OK |
FR7613807008043001965405255 | 038-CPT30019654052 | A vue | 459.56 | EUR | OK | OK | |||||
FR7613807008043001965405352 | 038-CPT30019654053 | A vue | 2 165.50 | EUR | OK | OK | |||||
Marie | Retraité
(PART) |
D0999991I0 | 12345678 | 13807 | FR7613807008043001965406128 | 038-CPT30019654061 | A vue | 1 754.03 | EUR | OK | OK |
FR7613807008043001965406225 | 038-CPT30019654062 | A vue | 11 429.00 | EUR | OK | OK | |||||
Thomas | Etudiant
(PART) |
D0999980 | 12345678 | 13807 | FR7613807008043001965407195 | 038-CPT30019654071 | A vue | 749.27 | EUR | OK | OK |
FR7613807008043001965407292 | 038-CPT30019654072 | A vue | -20 000.00 | EUR | KO | OK | |||||
Alix | Cadre
(PART) |
D0999992I0 | 12345678 | 13807 | FR7613807008043001965408165 | 038-CPT30019654081 | A vue | 52.00 | EUR | OK | KO |
FR7613807008043001965408262 | 038-CPT30019654082 | A vue | 395.45 | EUR | KO | OK | |||||
FR7613807008043001965408359 | 038-CPT30019654083 | A vue | 298.19 | EUR | OK | OK | |||||
Tech’n Co | Entreprise
(ENT) |
D0999993I0 | 12345678 | 13807 | FR7613807008043001965409135 | 038-CPT30019654091 | A vue | 63 917.00 | EUR | KO | KO |
Adam | Entrepreneur
(PRO) |
D0999994I0 | 12345678 | 13807 | FR7613807008063031966574122 | 038-CPT30319665741 | A vue | 0.00 | EUR | OK | OK |
FR7613807008063031966574219 | 038-CPT30319665742 | A vue | -2 894.05 | EUR | OK | OK | |||||
Lea | Cadre
(PART) |
755238649 | 12345678 | 13807 | FR7617515000920400430518020 | 038-CPT04004305180 | A vue | -150.00 | EUR | OK | OK |
SARL UNIPERSONNELLE 2640 | Commerçant
(ENT) |
D0999995I0 | 12345678 | 13807 | FR7613807008063042100847972 | 038-CPT30421008479 | A vue | 0.00 | EUR | OK | OK |
FR7613807008060602191786661 | 038-CPT06021917866 | A vue | 139 613 054.35 | EUR | OK | OK | |||||
FR7613807002353032165639297 | 038-CPT30321656392 | A vue | 701 246 591.14 | EUR | OK | OK | |||||
FR7613807002353092101653050 | 038-CPT30921016530 | A vue | 99 792.13 | EUR | OK | OK | |||||
FR7613807002353092152355047 | 038-CPT30921523550 | A vue | 1 015 745.35 | EUR | OK | OK |
Marc
42 ans – Nantes Célibataire – Cadre dans la fonction publique – 18 ans d’expérience 3 comptes à vue Sa vie / Son Histoire / Son travail
Ses buts
|
Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Marie
73 ans – Nantes Mariée – Retraitée du secteur privée 2 comptes à vue Sa vie / Son Histoire / Son travail
Ses buts
|
Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Thomas
21 ans – Nantes Etudiant – Ecole d’ingénieur informatique privée 2 comptes à vue Sa vie / Son Histoire / Son travail
Ses buts
|
Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Alix
32 ans – Nantes Mariée – 3 enfants Cadre – Employé du secteur privé 3 comptes à vue 3 cartes à débit différé Sa vie / Son Histoire / Son travail
Ses buts
|
Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Tech’n Co
Créée par Dominique – Nantes 37 ans – Mariée – 2 enfants 1 compte à vue 1 carte à débit différé Sa vie / Son Histoire / Son travail
Ses buts
|
Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Adam
29 ans – Montpellier Célibataire – Entrepreneur – 4 ans d’expérience 2 comptes à vue 2 cartes à débit différé Sa vie / Son Histoire / Son travail
Ses buts
|
Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Léa
35 ans – Lyon Mariée – Cadre chez un assureur – 10 ans d’expérience 1 compte à vue Sa vie / Son Histoire / Son travail
Ses buts
|
Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
SARL UNIPERSONNELLE 2640
Dijon 5 comptes à vue et une carte à débit différé Sa vie / Son Histoire / Son travail
Ses buts
|
Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Comment récupérer son jeton d'accès OAUTH2 ?
Schéma du principe de récupération du jeton d’accès OAUTH2
En tant que développeur d’une application désirant utiliser cette API, l’obtention d’un jeton d’accès OAUTH2 vous est nécessaire et se fait grâce au processus suivant :
Références
- Section 3.4.3.2 de la spécification STET v1.4.0.47 : https://www.stet.eu/en/psd2/
- OAuth 2.0 Authorization Framework : https://tools.ietf.org/html/rfc6749#section-4.1
Développement pas à pas
1. Le client vous indique l’identité de sa banque teneur de compte.
2. Vous initiez la séquence de récupération du jeton d’accès OAUTH2 en redirigeant le client via son navigateur internet vers l’infrastructure informatique d’autorisation de la banque teneur de compte, le détail des liens et des paramètres se trouvent ci-après :
Voir aussi [STET Framework page 21]
GET /authorize?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope={scope}[&state={state}]
Nom | Description | Type | |
response_type | [1..1] | Type de jeton attendu | Chaîne [10] => doit être renseignée avec le « code » |
client_id | [1..1] | Votre identification en tant que TPP | Chaîne[34] =>
Si l’enregistrement du TPP a été réalisé au travers du processus de « GO Live » via notre portail BPCE API (ancienne procédure)
Ou si l’enregistrement du TPP a été réalisé via l’API register (procédure actuelle)
|
redirect_uri | [0..1]
[1..1] |
URL de re-routage vers votre application | Chaîne [140] => champ obligatoire pour les Banques Populaires, la Banque Palatine et la Banque de Savoie |
scope | [0..1] | Spécifie les accréditations génériques sur lesquelles notre client et vous, vous vous êtes accordés :
Pour un AISP :
Pour un CBPII :
|
Chaîne [140] => les espaces délimitent la liste des rôles |
state | [0..1] | Etat interne qui peut être utilisé par vous pour gérer le contexte | Chaîne [34] |
3. La banque teneur de compte (ASPSP) va :
- Identifier et authentifier le client par l’une des méthodes d’authentification forte qu’elle propose et présente au client;
- Effectuer des vérifications liées à votre profil en tant qu’AISP ou CBPII (validité des certificats QWAC et QSealc et de votre rôle dans le référentiel de place, non révocation de votre profil, etc.).
4. Une fois ces vérifications effectuées et si elles sont concluantes, la banque va vous rediriger notre client vers votre site en utilisant l’URL de « call-back » et les paramètres ci-après. A noter que vous devrez nous communiquer cette URL lors de votre enregistrement en tant que TPP consommateur de nos API,
- soit lors du processus de « GO Live » via notre portail BPCE API (ancienne procédure) ;
- soit via l’API register (procédure actuelle).
Voir aussi [STET Framework page 22]
Nom | Description | Type | |
code | [1..1] | Code court utilisé pour récupérer le jeton d’accès | Chaîne [34] |
state | [0..1] | Etat interne si fourni par vous | Chaîne [34] |
5. Vous allez pouvoir alors demander directement à la banque le jeton d’accès OAUTH2 via un appel de type POST envoyé avec les paramètres suivants :
Voir aussi [STET Framework page 22]
Nom | Description | Type | |
grant_type | [1..1] | Type d’autorisation requise | Chaîne [34] => doit être renseignée avec le « authorization code » |
code | [1..1] | Code court fourni précédemment par l’ ASPSP | Chaîne [34] |
redirect_uri | [1..1] | URL de re-routage du TPP | Chaîne [140] => doit être égale au redirect_uri fournie dans la requête GET /token. |
client_id | [1..1] | Identification du TPP | Chaîne[34] =>
Si l’enregistrement du TPP a été réalisé au travers du processus de « GO Live » via notre portail BPCE API (ancienne procédure)
Ou si l’enregistrement du TPP a été réalisé via l’API register (procédure actuelle)
|
Exemple
POST /token HTTP/1.1 Host: server.example.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &client_id={clientId}
6. La banque teneur de compte (ASPSP) va :
- Effectuer des vérifications liées à votre profil en tant qu’AISP ou CBPII (validité des certificats QWAC et QSealc et de votre rôle, 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, la banque va vous renvoyer une réponse HTTP200 (OK) qui contiendra les données suivantes :
Voir aussi [STET Framework page 23]
Nom | Description | Type | |
access_token | [1..1] | Jeton d’accès fourni par l’ASPSP au TPP | Chaîne [140] |
token_type | [1..1] | Type du jeton d’accès fourni (« Bearer » or « MAC ») | Chaîne [10] => doit être renseignée avec « Bearer » |
expires_in | [0..1] | Durée de vie du jeton, en secondes. Le jeton peut être utilisé plusieurs fois tant qu’il n’a pas expiré. | Numérique |
refresh_token | [0..1] | Jeton de rafraîchissement qui peut être utilisé dans le cas d’une future requête de renouvellement de jeton. | Chaîne [140] |
Exemple
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { « access_token »: »2YotnFZFEjr1zCsicMWpAA », « token_type »: »example », « expires_in »:3600, « refresh_token »: »tGzv3JOkF0XG5Qx2TlKWIA » }
8. Dès que le jeton d’accès OAUTH2 délivré par la banque (valable 180 jours) a été récupéré par vos soins, vous pourrez le présenter pour pouvoir consommer l’API (voir les cas d’usage pour les méthodes de l’API).
Authentification du client
Méthodes d’identification du client
Il existe trois méthodes différentes pour l’identification du client qui se doit d’être pertinente pour l’ASPSP (établissement de crédit teneur de compte).
Celles-ci sont implémentées de différentes manières :
- soit durant le processus d’authentification (cf. § 3.4), pour la plupart des cas d’utilisation concernant les AISP et les CBPII;
- soit durant le consentement, par exemple dans le cas d’une requête de paiement (cf. § 3.5)
Principe pour la méthode REDIRECT > cette méthode s’applique pour les Banques Populaires, la Banque Palatine et la Banque de Savoie
Dans le cas de cette méthode, l’identification du client est faite entièrement par l’ASPSP.
L’AISP va orienter le client vers le service d’authentification de l’ASPSP, ce qui veut dire que le client va délaisser temporairement l’interface de l’AISP pour s’identifier via l’interface de l’ASPSP.
Si l’AISP a déjà récupéré un identifiant du client qui peut être approuvé par l’ASPSP de manière sûre alors dans ce cas l’identifiant peut être inclus dans la redirection à condition que le protocole de redirection le permette.
Une fois l’identification achevée, l’ASPSP va rediriger le client vers l’interface de l’AISP.
Exceptions à l’authentification forte
Les exceptions à une authentification forte sont prévues par les normes techniques de réglementation (éditées par l’Agence Bancaire Européenne) portant sur l’authentification forte et tout particulièrement sur l’initiation des services de paiement.
Dans ce cas, l’API offre la possibilité au TPP de fournir toute information utile à l’ASPSP.
Au final, c’est l’ASPSP qui est garant de la décision d’appliquer ou non cette exception.
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 propres aux Banques Populaires décrites dans la section « Limitations ».
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/accounts.
La rubrique « 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 de l’API correspond à la version V1.4.0.47 des spécifications STET et la v1.4.2 correspond à la version V1.4.2.17 des spécifications STET.
Le principe de la durée de support est schématisé ci-dessous en prenant en compte l’article 30 (4) des RTS :
Versionning de l’API
Nos versions API | Version norme STET |
v1 | v1.4.0.47 |
v1.4.2 | v1.4.2.17 |
Vous pouvez consulter l’assistant virtuel au sujet des textes de la norme STET.
Evolutions importantes apportées depuis la première version livrée
Cas d’usage / Méthode(s) | Date d’effet | Description de l’évolution |
GET/transactions | 02 mai 2019 | Changement du format du champ « remittanceInformation » :
Documentation portail : mise à jour des exemples. |
GET/accounts GET/transactions | 02 mai 2019 | Changement du nommage du champ « resourceId » :
Documentation portail : mise à jour des exemples. |
GET/accounts GET/transactions GET/balances PUT/consent | 17 mai 2019 | Documentation portail : ajout de précisions sur le caractère obligatoire ou facultatif des paramètres et des champs des requêtes. |
GET/transactions | 17 mai 2019 | Rafraichissement des données de test (personas) : profondeur d’historique sur 3 moisDocumentation portail : mise à jour des exemples. |
GET/transactions | 29 mai 2019 | Correction de la règle de restitution de la liste des transactions lorsque le paramètre « afterEntryReference » est renseigné : la transactions correspondant au paramètre « afterEntryReference » renseigné ne fait pas partie de la liste restituée, seules les transactions ayant une identification technique supérieure à cette valeur sont incluses dans le résultat. |
Authentification et jeton d’accès OAuth2 | 21 juin 2019 | Documentation portail : correction des liens et des paramètres dans la description la séquence de récupération du jeton d’accès OAUTH2. le paramètre ‘redirect_url’ a été remplacé par ‘redirect_uri’ dans la requête GET le paramètre ‘response_type’ a été remplacé par ‘response_type’ |
Tous | 31 juillet 2019 | Documentation portail : description de l’assemblage sandbox en cible à fin août 2019 : ajouts de précisions (limitations, exemples, date de mise à disposition, etc.) sur l’ensemble des cas d’usage de l’API. |
Assemblage sandbox | 18 septembre 2019 | Documentation portail : description de l’assemblage sandbox complétée. Roadmap modifiée pour la sandbox et le live. |
Eligibilité | 10 octobre 2019 | Documentation portail :
|
Tous | 18 octobre 2019 | Documentation portail :
|
Assemblage sandbox / Comment récupérer son jeton d’accès OAUTH2 | 13 novembre 2019 | Documentation portail :
|
Comment utiliser le fallback | 21 novembre 2019 | Documentation portail :
|
Testez nos persona | 23 décembre 2019 | Documentation portail :
|
GET /transactions | 24 décembre 2019 | Documentation portail :
|
Historique des versions / roadmap | 30 décembre 2019 | Documentation portail :
|
Historique des versions / roadmap | 31 mars 2020 | Documentation portail :
|
Toutes | 8 juillet 2020 | Documentation portail :
|
GET /transactions | 12 avril 2021 | Documentation portail :
|
GET /transactions | 11 mai 2021 | Documentation portail :
|
Toutes | 19 juillet 2021 | Documentation portail :
|
Fallback
Jeton d’accès |
29 septembre 2021 | Documentation portail :
|
GET /balances | 6 avril 2022 | Documentation portail :
|
Vue d’ensemble | 28 août 2022 | Changements éditoriaux et rajout du cas App2App |
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 versions 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*.
(*) 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.
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 Gateway |
Date de décommissionnement |
v1 | v1.4.0.47 |
|
14 mars 2019 (première version)
7 octobre 2019 (mode REDIRECT) |
7 octobre 2019 | Fin 2022
(à confirmer) |
v1.4.2 | v1.4.2.17 |
|
8 juillet 2020 | 28 octobre 2020 |
Limitations
Limitations fonctionnelles
Limitations de cette API DSP2 en version 1.4.2
- Ne s’applique qu’aux comptes de paiements en euros actifs et accessibles en ligne (cf. texte de la Directive DSP2) => seuls les comptes à vue seront restitués
- N’utilise que le mode d’authentification REDIRECT (Authentification Forte du PSU demandée et gérée via la banque)
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)
- Implémente le mode de consentement mixte AISP, mais n’implémente pas le mode de consentement full AISP :
- par défaut, lorsqu’aucun consentement n’a été transmis, tous les comptes à vue sont accessibles
- mais le détail des soldes et transactions des comptes à vue ainsi que les encours carte et facturettes n’est accessible que pour les comptes à vue dont le consentement a été transmis
- Limite à 4 accès batch par jour calendaire pour chacune des méthodes de cette API (cf. cas d’usage pour chacune des méthodes pour voir les détails), mais ne fixe pas de limite lorsque c’est le PSU connecté qui interroge ses comptes à vue
- Ne permet pas de récupérer la liste des bénéficiaires de confiance d’un PSU : la notion de bénéficiaire de confiance n’existe pas pour les Banques Populaires (<=> un bénéficiaire enregistré et validé par une authentification forte et pour lequel il n’est plus demandé par la suite d’authentification forte pour valider un paiement)
- 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
- 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 et GET /end-user-identity sont disponibles
- Ne remonte que les cartes à débit différée actives et qui ont servi (présence de facturette CB sur le compte support de la carte) au moins une fois dans les deux derniers mois.
Limitations liées aux segments de clientèle
- Le particulier (PART) est une personne physique catégorisée comme « majeur capable »
- Les catégories « professionnel » (PRO) et « entreprise » (ENT) couvrent les personnes morales
Limitations liées aux types de comptes accessibles
- Les comptes accessibles via l’API AISP sont ceux disponibles sur la banque à distance, à savoir :
- majeur capable
- compte joint Mr et Mme
- compte joint Mr ou Mme
- entrepreneur individuel
- entreprise
- mineur rattaché
- mineur émancipé
- Le compte suivant n’étant pas accessible sur la banque à distance, il ne l’est pas non plus via l’API AISP :
- majeur sous tutelle
Limitations liées au moyen d’authentification forte en fonction du segment de clientèle
- Client particulier (PART) : équipement avec SMS OTP et/ou Sécur’pass. Sécur’pass est déclenché en priorité le cas échéant
- Client professionnel (PRO) : équipement avec SMS OTP et/ou Sécur’pass. Sécur’pass est déclenché en priorité le cas échéant
- Client entreprise (ENT) : équipement avec SMS OTP
Le tableau ci-dessous résume les limitations par méthode pour cette API (les noms des champs sont donnés en italique) :
Récupération de la liste de comptes à vue et des cartes à débit différé adossées à ces comptes (méthode « GET /accounts ») | Récupération des soldes des comptes à vue et des encours des cartes à débit différé adossées à ces comptes (méthode « GET /accounts/balances ») | Récupération des transactions des comptes à vue et des facturettes des cartes à débit différé adossées à ces comptes (méthode GET /accounts/transactions) |
|
|
|
Pagination des résultats affichés :
Deux paramètres sont disponibles pour personnaliser la pagination des résultats affichés à l’écran :
- le premier concerne le nombre de comptes / cartes par pages lors d’une requête de type GET /accounts. La valeur par défaut est fixée à 100.
- le deuxième concerne le nombre de transactions par pages lors d’une requête de type GET /accounts/transactions. La valeur par défaut est fixée à 200.
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 réelles, après avoir testé votre app en Try-it et en Assemblage sandbox, vous devez vous enregistrer en tant que TPP consommateur de nos API,
- soit lors du processus de « GO Live » via notre portail BPCE API (ancienne procédure) ;
- soit via l’API register (procédure actuelle) :
cf. textes DSP2/RTS Art. 30 (5). Les prestataires de services de paiement gestionnaires de comptes mettent à disposition un dispositif d’essai, comprenant une assistance et permettant des tests de connexion et de fonctionnement, afin que les prestataires agréés de services d’initiation de paiement, de services d’information sur les comptes et de services de paiement qui émettent des instruments de paiement liés à une carte ou les prestataires de services de paiement 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.
Si l’enregistrement du TPP a été réalisé au travers du processus de « GO Live » via notre portail BPCE API (ancienne procédure)
- Une seule app consommatrice peut être déclarée par le TPP (même OID = client_Id) sachant qu’il y a possibilité de gérer :
- les modèles de partenariat en marque blanche et en tiers-utilisateur;
- plusieurs certificats par app consommatrice / client_Id TPP et plusieurs URL de redirection.
Ou si l’enregistrement du TPP a été réalisé via l’API register (procédure actuelle)
- Plusieurs app consommatrices peuvent être déclarées par le TPP pour lui ou son/ses agents. Pour chacune, plusieurs certificats par app consommatrice / client_Id TPP et plusieurs URL de redirection peuvent être gérés.
La plage hebdomadaire du lundi matin de 2h à 6h est utilisée si besoin pour la maintenance des backends / des gateways et peut engendrer des requêtes KO le temps que les serveurs concernés aient tous été mis à jour pour l’établissement concerné.
Comme en mode test, le code établissement (voir ci-dessous) vous permettra d’adresser le bon référentiel client via le « endpoint » www.<codetab>.live.api.89c3.com ou www.<codetab>.live.api.banquepopulaire.fr aligné sur le nom de domaine de l’accès direct www.banquepopulaire.fr
Une fois choisi, ce point d’accès doit être conservé pour toutes les requêtes sous-jacentes.
Code établissement | Nom de l’établissement | Nom abrégé | Disponible en Try-it et Assemblage | Disponible en Production |
10807 | B.P Bourgogne Franche Comté | BPBFC | Oui | |
16807 | B.P AUvergne et Rhône-Alpes | BPAURA | Oui | |
10207 | B.P RIves de Paris + BICS | BPRI | Oui | |
18707 | B.P Val de France | BPVF | Oui | |
13507 | B.P du Nord | BPN | Oui | |
16607 | B.P Sud | BPS | Oui | |
10907 | B.P Aquitaine Centre Atlantique | BPACA | Oui | |
10907 | CMM Littoral du Sud OUest | CMSOU | Oui | |
14707 | B.P Alsace Lorraine Champagne | BPALC | Oui | |
17807 | B.P OCcitane | BPOC | Oui | |
13807 | B.P Grand Ouest | BPGO | Oui | Oui |
13807 | CMM Grand Ouest | CMMGO | Oui | Oui |
14607 | B.P MEDiterranée | BPMED | Oui |
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 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 é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).
Catégories
-
Cas d'usage
-
Comment tester l'API