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

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

Image

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 « Obtenir la liste des 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 rejeé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 essayez 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 « Transmettre la liste des comptes » ). 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 « Obtenir la liste des 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 /accounts/balances

La limite est de 4 accès batchs quotidiens maximum par PSU/compte pour GET /accounts/transactions par page d’accès

La limite est de 4 accès batchs quotidiens maximum par PSU/carte pour GET /accounts/balances

La limite est de 4 accès batchs quotidiens maximum par PSU/carte pour GET /accounts/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 :

Image

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

Roadmap

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

(*) Fonctionnalités Principales :

• Utilisation par le TPP du même endpoint que l’interface dédiée. Il dépend donc du code établissement 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 indisponibles de façon imprévue ou le système tomberait en panne (voir critères dans le texte RTS Art. 33), le TPP peut alors envoyer la requête :

POST https://www.<codetab>.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")

Image

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

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

X-Request-ID: 1234

fallback: 1

User-Agent: PostmanRuntime/7.16.3

Accept: */*

Cache-Control: no-cache

Host: www.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)

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éfini en avance par le TPP sur le même principe qu’une url de callback :

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

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

Requête

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

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

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

ou

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

ou

• si l’autre format d’appel des point d’accès a été utilisé http://www.<codetab>.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

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 via l’API Enregistrement DSP2.

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ées 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 HTTP 200 (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 « Cas d'usage » > « 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 ».

Obtenir la liste des comptes

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 « Cas d’usage » > « Récupérer votre jeton »).

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/balance , GET /accounts/transactions codeGET /end-user-identity.

Si vous 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é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/transactions si la carte à débit différée 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.
     
• 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é 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.

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.

Transmettre la liste des comptes

Principe 

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

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é 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é 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 aux 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 description des codes erreurs de ce service. 

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.

Obtenir les soldes

Principe 

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 « Cas d’usage » > « 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
• 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

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 :

3 types d’encours pourront être retournés dans le cas d’une carte passée en paramètre :

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 persona ».

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. 

Test d’acceptance

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

Obtenir les transactions

Principe

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 « Cas d'usage » > « 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 : }.
• 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 : }.
• 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

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 » :

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

Exemples

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 » } } }

Codes erreurs

Voici la liste de descriptions des codes erreurs de ce service. 

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.

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 « Cas d'usage » > « Récupérer votre jeton »).

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

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

Requête

GET /end-user-identity

Voir aussi la spécification de place STET V1.4.2.17 / Part III / Section 6.3 / page 8

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. 

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.

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 « Cas d'usage » > « Récupérer votre jeton ».

Assemblage sandbox

Introduction – précisions sur les fonctionnalités de la sandbox

La sandbox BPCE API peut être utilisée 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 « Cas d'usage » > « Récupérer votre jeton » ) ou le rafraîchir (voir la rubrique « Cas d'usage » > « Rafraîchir 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 » > « Tester 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 « Transmettre la liste des comptes » et « Obtenir 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 via l'API Enregistrement DSP2.

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 « Cas d'usage » > « Récupérer 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) :

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 Enregistrement DSP2 (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 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 Enregistrement DSP2 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 :

Image

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.

Image

L’identifiant de banque à distance du client est à saisir (voir la rubrique « Comment tester l’API » > « Tester nos persona » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires :

Image

2) Le client est redirigé vers un écran d’authentification forte proposé par son établissement bancaire pour valider son identité.

Image

Le code SMS pour authentification est à saisir (voir la rubrique « Comment tester l’API » > « Tester nos persona » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires :

Image

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 Enregistrement DSP2 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.

Exemple : https://bred.demoseo.turbosa.banquepopulaire.fr/Home/OAuth2Callback?code=NnZx1hqHY2CLkCFjiTwhJeflgNnCrB

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 access_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 Enregistrement DSP2 (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 Enregistrement DSP2 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 « Obtenir la liste des 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: 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 »
}
]
}

.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts?page=last »
},
« self »: {
« href »: « https://www..sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts »
},
« first »: {
« href »: « https://www..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..sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts?page=last »
},
« self »: {
« href »: « https://www..sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts »
},
« first »: {
« href »: « https://www..sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts »
},
« endUserIdentity »: {
« href »: « https://www..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..sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/balances »
},
« transactions »: {
« templated »: false,
« href »: « https://www..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..sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654052/balances »
},
« transactions »: {
« templated »: false,
« href »: « https://www..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..sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654053/balances »
},
« transactions »: {
« templated »: false,
« href »: « https://www..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 « Transmettre la liste des comptes« .

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 Enregistrement DSP2 (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 »

}

Tester nos persona

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

Cette page présente les jeux de données qui permettent de tester l’API :

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

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 :

Image

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}]

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 Enregistrement DSP2 (procédure actuelle).

Voir aussi [STET Framework page 22]

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]

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 HTTP 200 (OK) qui contiendra les données suivantes :

Voir aussi [STET Framework page 23]

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.

Politique de décommissionnement des versions de l’API

La politique du décommissionnement est fonction du cycle de vie des API, elle-même calée sur les versions des spécifications STET. Elle est schématisée ci-dessous pour la version N :

Image

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.

Limitations

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 entre crochets) :

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 via l’API Enregistrement DSP2 (procédure actuelle) :

Image

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 Enregistrement DSP2 (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.

Eligibilité

Les ressources de l’API Information sur compte ne peuvent être consommées que par des PSP ayant le rôle d’agrégateur (AISP). Ce statut est délivré par les autorités financières du pays dans lequel la demande est effectuée ; en France il s’agit de l’Autorité de Contrôle Prudentiel et de Résolution (ACPR), liée à la Banque de France.

L’obtention et la conservation d’un agrément relèvent de procédures rigoureuses afin d’apporter des garanties fortes aux utilisateurs des services de paiements, les formulaires étant disponibles sur le site de l’ACPR : https://acpr.banque-france.fr/autoriser/procedures-secteur-banque/tous-les-formulaires.

Une fois l’agrément donné, le format de cet identifiant (Organisation Identifier = OID) fourni par l’autorité compétente est :

PSDXX-YYYYYYYY-ZZZZZZZZ:

XX => code ISO 3166 du pays de l’autorité compétente hyphen-minus « – » (0x2D (ASCII), U+002D (UTF-8)) YYYYYYYY => 2-8 caractères du l’identifiant de l’autorité compétente (A-Z, pas de séparateur) hyphen-minus « – » (0x2D (ASCII), U+002D (UTF-8)) ZZZZZZZZ => identifiant du PSP spécifié par l’autorité nationale compétente (sans restriction sur le nombre – ou sur le type – de caractère utilisé)

Cet identifiant OID est important à 2 titres :

• il servira à vous identifier lors des appels dans les requêtes des API STET (via le paramètre « client_id »)
• il devra être présent dans les certificats eIDAS que vous fournirez au teneur de compte (voir ci-dessous)

De plus, vous devez disposer de certificats délivrés par une autorité de certification reconnue (Qualified Certification Service Providers – QTSP: https://webgate.ec.europa.eu/tl-browser/#/) conformes au règlement eIDAS (electronic IDentification And trust Services : https://www.ssi.gouv.fr/entreprise/reglementation/confiance-numerique/le-reglement-eidas/) et respectant la norme ETSI (https://www.etsi.org/deliver/etsi_ts/119400_119499/119495/01.02.01_60/ts_119495v010201p.pdf).

Afin de consommer les API DSP2 proposées sur ce portail, le TPP doit enrôler son app et nous transmettre via notre API Enregistrement DSP2 des certificats de production signés par une autorité de certification agréée :

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

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

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

Seules les clés publiques au format .pem sont nécessaires. Des contrôles sur les données des certificats seront effectués à partir des registres Français (REGAFI : https://www.regafi.fr) et Européen (ABE ou EBA : https://euclid.eba.europa.eu/register/pir/disclaimer).

Versionning de l’API

Important changes made since the first version delivered