BTP Banque – Information sur compte – (Norme STET v1.4.2)

Comment agréger les données

Un client multi bancarisé souhaite accéder à l’ensemble de ses données afin d’en avoir une vision consolidée.

Via cette API « information sur compte » mise à disposition par les teneurs de comptes, vous pouvez demander en temps réel l’accès à l’une et/ou l’autre des données que le client a autorisé SANS lui demander ses identifiants de connexion en ligne.

Les ressources de cette API ne peuvent être consommées que si vous avez obtenu le rôle de prestataire de Services d’Information sur les Comptes (« TPP AISP »), ce prérequis étant décrit dans voir la rubrique « Éligibilité« .

Le processus global est le suivant :

Le client souhaite utiliser vos services afin de consolider des informations d’un ou plusieurs comptes de paiement détenus auprès de banques, dont l’une d’entre-elles est la BTP Banque. Il vous l’indique donc laquelle à travers vos interfaces.

Lors de ce premier échange, vous allez faire une demande de jeton d’autorisation (et un jeton de rafraichissement). Le principe de base est, qu’en tant que TPP AISP, vous devez obtenir ces jetons AVANT de consommer des ressources de l’API. Ce jeton est généré par le teneur de compte (ASPSP) APRES avoir identifié et authentifié le client.

En tant que teneur de compte :

• nous allons vérifier vos certificats et agréments

• et via le jeu de la redirection, nous allons identifier et authentifier fortement le client afin de pourvoir générer le jeton d’accès

Si l’autorisation est accordée par le client, vous pourrez alors récupérer les jetons OAUTH2 via des échanges sécurisés avec la plateforme BPCE API (voir la rubrique « Vue d’ensemble » > « Récupérer votre jeton« ).

En présentant ce jeton d’autorisation, vous pourrez alors consommer les ressources de l’API « information sur compte » afin de :

• demander la liste des comptes éligibles
• nous transmettre le consentement client
• accéder de manière sécurisée aux données dont l’accès a été autorisé (voir la rubrique « Vue d’ensemble » > « Comment consommer l’API ?« ).

Au bout du délai réglementaire de 180 jours, ce processus devra être reconduit (voir la rubrique « Vue d’ensemble » > « Rafraîchir votre jeton« ).

NB : le gestionnaire de compte ASPSP a la possibilité de vous refuser l’accès pour différents motifs justifiés (API non conforme, compte bloqué entre-temps, etc.).

Consommer l'API

Afin d’interroger une API, la version de l’API inclut le numéro de version dans l’URI appelée, soit par exemple : /stet/psd2/v1.4.2/accounts.

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

Vous devez aussi être familier avec la terminologie DSP2 et les abréviations utilisées. Vous pouvez également utiliser la foire aux questions (FAQ), l’assistant virtuel ou le glossaire.

Pour rappel, il faudra que vous :

• exécutiez une authentification mutuelle avec vos certificats

• fassiez une demande de jeton d’accès (Oauth2) via le mode « redirection »

• récupéreriez la liste des comptes courants

• demandiez le consentement client et le transmettre au teneur de compte (ASPSP).

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

• le solde
• et/ou l’historique des transactions
• et/ou le nom et prénom du détenteur du compte

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

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

Dans l’environnement de production, l’accès aux données de production se fait via le point d’entrée www.<codetab>.live.api.89C3.com (voir la rubrique « Limitations« ).

Obtenir la liste des comptes d’un client

Description

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

Prérequis

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

Echange de données

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

Enregistrer le consentement d’un client (AISP)

Description

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

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

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

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

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

Le consentement est vérifié à chaque requête passée d’accès à ces informations.

Prérequis

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

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

Echange de données

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

Obtenir le solde d’un compte

Description

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

Prérequis

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

Echange de données

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

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

Obtenir la liste des transactions d’un client

Description

Cet appel permet de récupérer la liste des opérations d’un compte du PSU pour lequel l’AISP est connecté.

Les transactions obtenues sont inférieures ou égales à 90 jours par rapport à la date du jour.

Prérequis

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

Echange de données

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

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

Récupérer l’identité du client

Vous récupérez l’identité du PSU connecté via un accès à la méthode GET /end-user-identity (voir le cas d’usage technique associé).

Récupérer votre jeton

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

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

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

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

Voir aussi la spécification de place STET V1.4.2.17 / Part I / section 3.4.3

3. Le teneur de compte (ASPSP) va :

• Identifier et authentifier son client par l’une des méthodes d’authentification forte qu’elle propose et qu’il présente au client ;

• Effectuer des vérifications liées à votre profil en tant qu’AISP ou CBPII (validité de vos certificats QWAC et QSEALC et de votre rôle, non révocation de votre profil, etc.)

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

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

• Si le PSU a autorisé la récupération de ses données par l’AISP

• Ou en cas de refus du consentement

• Ou si la cinématique d’identification et d’authentification est interrompue à l’une de ses étapes (exemple : timeout sur l’écran d’identification ou sur l’écran d’authentification forte).

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

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

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

Voir aussi la spécification de place STET V1.4.2.17 / Part I / section 3.4.3

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

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

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

Voir aussi la spécification de place STET V1.4.2.17 / Part I / section 3.4.3 ET V1.4.0.47 / Part I / section 3.4.3.2

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

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

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

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

Exemple

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

Rafraîchir votre jeton

Principe

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

Règles de base

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

• Le jeton d’accès a une durée de validité courte (de l’ordre d’une heure max) sur un périphérique ou une application de notre client

• Le jeton de rafraîchissement a une durée de vie de 180 jours

• Le jeton de rafraîchissement et le jeton d’accès doivent pouvoir être révoqués à tout moment

• Si le jeton d’accès est révoqué alors le jeton de rafraîchissement doit l’être aussi et réciproquement

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

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

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

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

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

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

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

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

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

Revocation des jetons

Une révocation des jetons d’accès (valable 180 jours) est possible avant l’expiration du jeton, voir la spécification STET V1.4.2 / partie 1 « Framework » / paragraphe 3.4.2.8 « Refresh token revocation ».

Exemple

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

Utiliser le fallback

Principe

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

Si l’infrastructure de production « passerelle BPCE API Live » exposant les API DSP2 est défaillante, le prestataire des services de paiements pourra utiliser la solution couvrant les « mesures d’urgence applicables à une interface dédiée » (ou « fallback ») dont le principe est le suivant :

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

Roadmap

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

(*) Fonctionnalités Principales :

• Utilisation par le TPP du même endpoint que l’interface dédiée.

• Un paramètre de requête (header « fallback:1 » présent ou absent) ajouté par le TPP permet de distinguer une requête « Fallback » d’une requête API via l’interface dédiée qui doit être utilisée systématiquement

• Authentification du TPP via authentification mutuelle TLS par un certificat eIDAS (QWAC)

• Sécurisation identique à celle d’un accès à la banque en ligne du PSU (même interface utilisée par le PSU qu’en accès direct, et mêmes moyens d’authentification du client)

• Dans le cadre de la montée en charge de l’usage de l’interface dédiée (API), il n’est pas mis en place de bascule dynamique : la solution fallback est toujours active

• La solution de fallback est une solution de secours ne devant pas être utilisée comme moyen principal d’accès pour proposer les services DSP2. Son usage en est monitoré et tout usage abusif par un/des TPP sera automatiquement reporté auprès de l’autorité nationale compétente.

Exemple

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

POST https://www.17515.live.api.89c3.com/stet/psd2/oauth/token

avec :

• son certificat eIDAS QWAC de production

• le paramètre header (fallback: »1″)

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

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

X-Request-ID: 1234

fallback: 1

User-Agent: PostmanRuntime/7.16.3

Accept: */*

Cache-Control: no-cache

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

Accept-Encoding: gzip, deflate

Content-Length: 67

Connection: keep-alive

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

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

HTTP/1.1 302 Found

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

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

Content-Length: 870

Connection: close

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

</head><body>

<h1>Found</h1>

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

</body></html>

3. Une fois redirigé, le TPP doit utiliser ensuite les identifiants du PSU via sa méthode propriétaire

Pour plus de détails sur la requête POST, voir spécifications STET

Limites

Les contraintes de cette solution sont les suivantes :

• Pas de réutilisation du contexte de l’interface dédiée, ni du jeton d’accès (valable 180 jours actuellement)

• Seules les fonctionnalités DSP2 présentes sur la banque en ligne (référence: banque à distance sur internet fixe) sont accessibles via le fallback. Par exemple, les services de banque en ligne ne proposent pas de paiement e-commerce (cette fonctionnalité PISP n’est donc pas disponible en mode fallback)

• Le client utilisateur des services (PSU) doit être connecté à l’application du TPP (pas de possibilité de traitement batch AISP pour venir récupérer les données consenties du client). La DSP2 imposant également un renforcement des moyens d’authentification forte (AF/SCA) systématique pour les accès à la banque à distance/en ligne, les moyens d’authentification fournis aux clients PSU seront utilisés (liste non exhaustive) :
  • Soft token Sécur’Pass
  • OTP SMS
  • Clé physique (pour les entreprises)

Activer l'App2App

Introduction

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

Prérequis

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

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

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

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

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

Requête

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

Brand	App2App endpoint
	http://www.40978.live.api.palatine.fr/stet/psd2/oauth/authorize
	http://www.<codetab>.live.api.banquepopulaire.fr/stet/psd2/oauth/authorize (voir la liste des <codetab> sur la fiche produit API Banque Populaire)
	http://www.10548.live.api.banque-de-savoie.fr/stet/psd2/oauth/authorize
	http://www.<codetab>.live.api.caisse-epargne.fr/stet/psd2/oauth/authorize (voir la liste des <codetab> sur la fiche produit API Caisse d’Epargne)
	http://www.12579.live.api.banquebcp.fr/stet/psd2/oauth/authorize
	http://www.42559.live.api.credit-cooperatif.coop/stet/psd2/oauth/authorize
	http://www.30258.live.api.btp-banque.fr/stet/psd2/oauth/authorize
	http://www.18919.live.api.natixis.com/stet/psd2/oauth/authorize

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

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

ou

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

ou

• si l’autre format d’appel des point d’accès a été utilisé http://www.<codetab>.live.api.89c3.com/stet/psd2/oauth/authorize (ce qui peut être utile comme backup en cas de problème avec l’App2App)

Publications réglementaires

/stet/psd2/v1.4.2/accounts/{accountResourceId}/balances

accountsBalances

Résumé

Retrieval of an account balances report (AISP)

Description

This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification – The TPP has been registered by the Registration Authority for the AISP role – The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2). – The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any. – The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. – The TPP has previously retrieved the list of available accounts for the PSU The AISP requests the ASPSP on one of the PSU’s accounts. The ASPSP answers by providing a list of balances on this account. – The ASPSP must provide at least the accounting balance on the account. – The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible. – Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.

Scopes

• aisp
• extended_transaction_history
• cbpii

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/accounts

accountsGet

Résumé

Retrieval of the PSU accounts (AISP)

Description

This call returns all payment accounts that are relevant the PSU on behalf of whom the AISP is connected. Thanks to HYPERMEDIA, each account is returned with the links aiming to ease access to the relevant transactions and balances. The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results. – The TPP has been registered by the Registration Authority for the AISP role. – The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2). – The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any. – The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The TPP sends a request to the ASPSP for retrieving the list of the PSU payment accounts. The ASPSP computes the relevant PSU accounts and builds the answer as an accounts list. The result may be subject to pagination in order to avoid an excessive result set. Each payment account will be provided with its characteristics.

Scopes

• extended_transaction_history
• cbpii
• aisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/accounts/{accountResourceId}/transactions

accountsTransaction

Résumé

Retrieval of an account transaction set (AISP)

Description

This call returns transactions for an account for a given PSU account that is specified by the AISP through an account resource identification. The request may use some filter parameter in order to restrict the query – on a given imputation date range – past a given incremental technical identification
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results. – The TPP has been registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2). – The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) is any. – The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. – The TPP has previously retrieved the list of available accounts for the PSU
The AISP requests the ASPSP on one of the PSU’s accounts. It may specify some selection criteria.
The ASPSP answers by a set of transactions that matches the query. The result may be subject to pagination in order to avoid an excessive result set. The default transaction set, in the absence of filter query parameter, has to be specified and documented by the implementation.

Scopes

• extended_transaction_history
• cbpii
• aisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/consents

consentPut

Résumé

Forwarding the PSU consent (AISP)

Description

In the mixed detailed consent on accounts – the AISP captures the consent of the PSU
– then it forwards this consent to the ASPSP This consent replaces any prior consent that was previously sent by the AISP. – The TPP has been registered by the Registration Authority for the AISP role. – The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2). – The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any. – The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The PSU specifies to the AISP which of his/her accounts will be accessible and which functionalities should be available. The AISP forwards these settings to the ASPSP. The ASPSP answers by HTTP201 return code.

Scopes

• extended_transaction_history
• cbpii
• aisp

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

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

endUserIdentity

Résumé

Retrieval of the identity of the end-user (AISP)

Description

This call returns the identity of the PSU (end-user). – The TPP has been registered by the Registration Authority for the AISP role. – The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2). – The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any. – The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The AISP asks for the identity of the PSU. The ASPSP answers with the identity, i.e. first and last names of the end-user.

Scopes

• aisp
• cbpii
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/funds-confirmations

fundsConfirmation

Résumé

Payment coverage check request (CBPII)

Description

The CBPII can ask an ASPSP to check if a given amount can be covered by the liquidity that is available on a PSU cash account or payment card. – The TPP has been registered by the Registration Authority for the CBPII role – The TPP and the PSU have a contract that has been registered by the ASPSP – At this step, the ASPSP has delivered an « Authorization Code », a « Resource Owner Password » or a « Client Credential » OAUTH2 access token to the TPP (cf. § 3.4.2). – Each ASPSP has to implement either the « Authorization Code »/ »Resource Owner Password » or the « Client Credential » OAUTH2 access token model. – Doing this, it will edit the [security] section on this path in order to specify which model it has chosen – The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code », « Resource Owner Password » or « Client Credential » access token which allows the ASPSP to identify the relevant PSU. The CBPII requests the ASPSP for a payment coverage check against either a bank account or a card primary identifier.
The ASPSP answers with a structure embedding the original request and the result as a Boolean.

Scopes

• cbpii
• extended_transaction_history
• aisp

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}/o-confirmation

paymentRequestOConfirmation

Résumé

Confirmation of a payment request or a modification request using an OAUTH2 Authorization code grant (PISP)

Description

The PISP confirms one of the following requests or modifications: – payment request on behalf of a merchant – transfer request on behalf of the account’s owner – standing-order request on behalf of the account’s owner The ASPSP answers with a status of the relevant request and the subsequent Credit Transfer. – The TPP has been registered by the Registration Authority for the PISP role – The TPP was provided with an OAUTH2 « Client Credential » access token by the ASPSP (cf. § 3.4.2). – The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3) – The ASPSP has answered with a location link to the saved Payment Request (cf. § 4.5.4) – The TPP has retrieved the saved request in order to get the relevant resource Ids (cf. § 4.6). – The PSU has been authenticated by the ASPSP through an OAUTH2 authorization code grant flow (REDIRECT approach) and the PISP got the relevant token – The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its « OAUTH2 Authorization Code » access token Once the PSU has been  uthenticated through an OAUTH2 authorization code grant flow (REDIRECT approach), it is the due to the PISP to confirm the Request to the ASPSP in order to complete the process flow. The ASPSP must wait for confirmation before executing the subsequent Credit Tranfer.

Scopes

• pisp
• aisp
• extended_transaction_history
• cbpii

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/trusted-beneficiaries

trustedBeneficiaries

Résumé

Retrieval of the trusted beneficiaries list (AISP)

Description

This call returns all trusted beneficiaries that have been set by the PSU. Those beneficiaries can benefit from an SCA exemption during payment initiation. The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results. – The TPP has been registered by the Registration Authority for the AISP role. – The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2). – The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any. – The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The AISP asks for the trusted beneficiaries list. The ASPSP answers with a list of beneficiary details structure.

Scopes

• cbpii
• aisp
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

Obtenir la liste des comptes

Ce service permet :

• de lister tous les comptes éligibles*
• de récupérer les soldes des comptes
• de récupérer les URI pour les méthodes GET /accounts/balances et GET /accounts/transactions
• de récupérer l’URI pour la méthode GET /end-user-identity

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

Prérequis

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

Requête

Requête « GET /accounts »

Voir aussi la spécification de place STET V1.4.2.17 / Part II / section 4.2 / page 27

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

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

Résultat retourné

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

• Cet appel vous permet de récupérer la liste de tous les comptes de notre client sans leurs soldes, sans les URI pour les méthodes GET /accounts/balances, GET /accounts/transactions et GET /end-user-identity

Si vous avez transmis au préalable au moins un compte consenti par notre 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, alors :

• Cet appel vous permet de récupérer la liste de tous les comptes consentis du client détenteur avec :

• • Leurs soldes si le compte fait parti de la liste « balances » transmise via la méthode PUT /consents
• • L’URI pour la méthode GET /accounts/balances si le compte fait parti de la liste « balances » transmise via la méthode PUT /consents
• • L’URI pour la méthode GET /accounts/transactions si le compte fait parti de la liste « transactions » transmise via la méthode PUT /consents
• • L’URI pour la méthode GET /accounts/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 informations pour les comptes non consentis ou non éligibles.

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, pour un client donné. En revanche, le nombre d’accès n’est pas limité lorsque c’est le client connecté qui interroge directement ses comptes.

Exemple

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

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

Remarque :

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

Voir aussi la spécification de place STET V1.4.0.47 / Part III / section 5.1 / page 5

Tests d’acceptance

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

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

Le scope OAuth2 = aisp sauf indication contraire.

Gestion du consentement

Ce service obligatoire (via le « consentement mixte AISP » imposé) vous permet de transmettre à la banque (ASPSP) les comptes pour lesquels son détenteur (PSU) vous a consenti à consulter en détail les soldes et / ou les transactions.

Prérequis

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

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

Cependant, si vous connaissez déjà le ou les IBAN des comptes de paiements du client, vous pouvez nous les transmettre directement via la méthode PUT /consents.

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

Requête

Requête « PUT /consents »

Voir aussi la spécification de place STET V1.4.2.17 / Part II / section 4.4 / page 15

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

• « balances » => accès aux soldes d’un ou plusieurs comptes : le solde des comptes est accessible via la méthode GET /accounts/balances pour les comptes consentis uniquement

• « transactions » => accès à l’historique des transactions d’un ou de plusieurs comptes : les transactions des comptes sont accessibles via la méthode GET /accounts/transactions pour les comptes consentis uniquement

• « psuIdentity » => accès à l’identité de notre client (nom et prénom pour un client de type « particulier », ou la raison sociale pour une personne morale)

• « trustedBeneficiaries » => accès à la liste des bénéficiaires de confiance : cette fonctionnalité n’est pas gérée dans la banque en ligne (quelque soit la valeur de ce champs true ou false, elle n’est donc pas prise en compte)

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

Le consentement enregistré du client est vérifié à chaque requête passée pour les méthodes GET /accounts, GET /accounts/balances et GET /accounts/transactions.

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.

ATTENTION :

• Si vous ne transmettez aucun compte via la méthode PUT /consents, alors que des comptes avaient été consentis via le dernier appel à cette méthode, cela signifie que le client a révoqué tous les comptes consentis

• Si aucun compte n’est consenti ou si le client a révoqué tous les comptes consentis, la méthode GET /accounts vous permet de récupérer la liste de tous les comptes, mais l’accès au solde et à l’historique des transactions n’est pas/plus possible.

• La résultante est que, pour récupérer des nouveaux comptes, il faut envoyer un PUT /consents à vide au préalable

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é

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

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

Exemple

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

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

Voir aussi la spécification de place STET V1.4.0.47 / Part III / section 5.3 / page 7

Tests d’acceptance

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

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

Le scope OAuth2 = aisp sauf indication contraire.

Obtenir les soldes

Ce service permet de lister les soldes d’un compte de paiement d’un client.

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

Prérequis

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

• L’IBAN du compte doit nous avoir été transmis dans la liste « balances » de la méthode PUT /consents et ne doit pas avoir été révoqué depuis (<=> pas d’annule et remplace via PUT /consents sans cet IBAN dans la liste « transactions »)

• L’ »accountResourceId » permettant d’interroger cette méthode pour ce compte courant, est récupéré via le résultat de la requête GET /accounts dans la rubrique « resourceId » pour le compte correspondant à cet IBAN, c’est-à-dire tel que « accountId »: {« iban »: » » }
• L’URI pour l’accès à cette méthode est donnée via la rubrique « _links »: {« balances »: »{« href »: …}} en résultat de la requête GET /accounts pour le « resourceId » du compte

Requête

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

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

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

Paramètre accountResourceId : compte pour lequel on veut consulter le solde.

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

Cet appel permet de récupérer la liste des soldes d’un compte du PSU (usager d’un service de paiement) pour lequel l’AISP (prestataire de service de paiement) est connecté.

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

Un seul type de solde sera retourné dans le cas d’un compte passé en paramètre : le solde Comptable (« CLBD » dans la norme STET).

Il correspond au solde comptable en fin de période (fin de semaine, fin de mois, fin de trimestre, fin de semestre, fin d’année).

Vos accès à cette méthode sont limités à 4 accès batch maximum par jour, pour un client et pour un compte.

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

Exemple

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

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

Voir aussi la spécification de place STET V1.4.2.17 / Part II / Section 4.3.4 / page 31

Test d’acceptance

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

Obtenir les transactions

Ce service permet de lister les transactions d’un compte de paiments de notre client.

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

Prérequis

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

• L’IBAN du compte doit nous avoir été transmis dans la liste « transactions » de la méthode PUT /consents et ne doit pas avoir été révoqué depuis

ATTENTION : pas d’annule et remplace via PUT /consents SANS cet IBAN dans la liste « transactions »

• L’ »accountResourceId » permettant d’interroger cette méthode est récupéré via le résultat de la requête GET /accounts, rubrique « resourceId » pour le compte correspondant à cet IBAN, c’est-à-dire que « accountId » : {« iban »: »<IBAN du compte> »}

• L’URI pour l’accès à cette méthode est donnée via la rubrique « _links » : {« transactions »: {« href »: …}} en résultat de la requête GET /accounts pour le « resourceId » du compte.

Requête

GET /account/{accoundResourceId}/transactions

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 éligible DSP2 pour lequel on veut consulter les opérations.

Paramètres facultatifs supportés:

• dateFrom => date limite de début pour les transactions recherchées. Les transactions ayant une date d’imputation égale au paramètre dateFrom sont restituées dans le résultat

• dateTo => date limite de fin pour les transactions recherchées. Les transactions ayant une date d’imputation égale au paramètre dateTo ne sont pas restituées dans le résultat.

• PSU-IP-ADDRESS => à alimenter si le client est connecté

Paramètres facultatifs non supportés :

• entryReferenceFrom

• entryReferenceTo

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

• YYYY-MM-DDTHH:MM:SS.SSS ou YYYY-MM-DDTHH:MM:SS.SSSZ

• YYYY-MM-DDTHH:MM:SS.SSS+HHMM

• YYYY-MM-DDTHH:MM:SS.SSS+HH:MM

Résultat retourné

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

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

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, pour un client et pour un compte donné.

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

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

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

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

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

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

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

« bankTransactionCode »: {

« domain »: « PMNT »,

« family »: « RCDT »,

« subFamily »: « ESCT »,

« code »: « 05 »,

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

}

Exemple

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

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

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

Tests d’acceptance

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

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

Obtenir l'identité du client

Cas d’usage

Ce service permet de récupérer l’identité d’un client qui vous a donné son consentement pour le faire.

Prérequis

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

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

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

Requête

GET /end-user-identity

Voir aussi la spécification de place STET V1.4.2.17 / Part II / section 4.6.4 / page 43

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

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

Résultat retourné

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

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

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

Exemple

Requête

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

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

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

Console Try-it

Principe

En vous connectant sur le portail, vous pouvez :

• faire appel à l’API souhaitée via un formulaire dans lequel vous sélectionnez votre application et le jeton d’accès
• puis vous saisissez les paramètres de la méthode que vous souhaitez tester (soit headers, soit body), ceux mentionnés par une étoile étant obligatoires

Une fois les paramètres saisis, vous pouvez lancer l’exécution de la requête : vous obtiendrez soit un résultat, soit une erreur.

Pour les méthodes « GET /accounts/transactions » et « GET /accounts/balances« , vous devez d’abord exécuter la requête « GET /accounts » pour récupérer la liste des comptes de dépôt ou courant. Cela vous permet de récupérer le « ressourceId » nécessaire pour passer ces méthodes pour le compte.

Les données utilisées pour faire le test en Try-it sont issues de persona (voir la rubrique « Comment tester l’API ? » > « Tester nos personas« ).

Paramètres du Try-it pour chacune des méthodes de l’API « Information sur compte »

NB : pour les paramètres de type de données « body », il est possible de copier-coller les exemples (partie gauche de l’écran) dans le formulaire (à droite de l’écran) en changeant juste les valeurs spécifiques au client choisi.

Paramètres communs à toutes les méthodes de l’API « Information sur compte »

Paramètres propres à la méthode « Obtenir les soldes d’un compte » – GET accounts/{}/balances

Paramètres propres à la méthode « Obtenir les transactions d’un compte pour obtenir la liste des comptes » – GET /accounts/{}/transactions

Assemblage Sandbox

Introduction

La sandbox BPCE API peut être accédée directement via votre application : c’est le mode assemblage.

Cet ASPSP étant sur le même backend que les Caisses d’Epargne (CE), le format des données retournées via API sera identique.

Vous pouvez donc utiliser les données CE en sandbox tel que décrit dans le cas d’usage « https://www.api.89c3.com/fr/component/bpceportal/products/357/usecases/373« .

Historique des versions

Version de la norme STET utilisée pour l’API

Cette API REST est conforme à la spécification interbancaire française STET (https://www.stet.eu/en/psd2/), version v.1.4.2.17, afin de répondre aux exigences règlementaires de la DSP2. Elle tient compte des limitations fonctionnelles décrites dans la section « limitations ».

Pour rappel :

• les textes de la directive de paiement numéro 2 (DSP2, référence UE 2015/2366 du 25/11/2015) sont rentrés en application le 13 janvier 2018 : http://eur-lex.europa.eu/legal-content/FR/TXT/?uri=CELEX:32015L2366

• ils ont été complétés par les normes techniques de réglementation (NTR, règlement délégué UE 2018/389) relatives à l’authentification forte du client et à des normes ouvertes communes et sécurisées de communication dont la date d’application se situe au 14 septembre 2019. Ces normes sont les RTS (Rules Technical Standards) : https://eur-lex.europa.eu/legal-content/FR/TXT/?toc=OJ%3AL%3A2018%3A069%3ATOC&uri=uriserv%3AOJ.L_.2018.069.01.0023.01.FRA

En France, l’ordonnance n° 2017-1252 du 9 août 2017 transpose la directive DSP2 dans la partie législative du code monétaire et financier. L’ordonnance est complétée au plan réglementaire par les décrets n° 2017-1313 et n° 2017-1314 du 31 août 2017 et les cinq arrêtés du 31 août 2017.

Les utilisateurs peuvent également consulter l’assistant virtuel en cliquant sur le pictogramme sur la page d’accueil du portail.

Description du support

Conformément à l’article 30 (5) des RTS, une assistance pour les prestataires PSP tiers est mise à disposition. Ce support est accessible via le formulaire sur ce portail BPCE API, ou via https://www.api.89c3.com/fr/nous-contacter. Les réponses se font pendant les heures de travail ouvrées.

Le principe général du support est schématisé ci-dessous en prenant en compte les délais réglementaires prévus à l’article 30 (4) des RTS :

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

Roadmap

Politique de décommissionnement des versions de l’API

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

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 fonctionnelles

Limitations de cette API DSP2 en version 1.4.2

• Ne s’applique qu’aux comptes de paiements (le critère déterminant réside dans la faculté d’exécuter des opérations de paiement quotidiennes à partir d’un tel compte géré par le système d’information central « backend », source des informations remontées par les API), en euros et éligibles (compte de paiements actif – non bloqué ni sous séquestre-, et accessible en ligne, cf. texte de la Directive DSP2)

• N’utilise que le mode d’authentification par redirection (Authentification Forte du client demandée et gérée via la banque teneur de compte du client utilisateur du service de paiement)

NB : le TPP n’a pas la possibilité de fournir à l’ASPSP les données de sécurité personnalisées du client à des fins d’authentification, et donc, seuls les écrans de redirection et d’authentification forte (SCA) de l’ASPSP doivent être utilisés (l’encapsulage de ces écrans par le TPP est interdit au regard des articles PSD2 #97.5 et RTS #31)

• N’implémente que le mode de consentement « mixte AISP » via la méthode PUT /consents qui devient obligatoire :
  • par défaut, lorsqu’aucun consentement n’a été transmis, tous les comptes à vue sont remontés
  • mais le détail des soldes et transactions exécutées n’est accessible que pour les comptes de paiements dont le consentement a été transmis par le TPP

• Ne fixe pas de limite d’accès (rate limit) lorsque c’est le PSU connecté qui interroge ses comptes de paiements (PSU-IP-ADDRESS fourni), sinon limité à 4 accès à l’initiative du TPP (cf. texte de la Directive DSP2) :
  • par jour calendaire (00h00 – 23h59:59:999)
  • par TPP OID
  • par ASPSP / point d’accès
  • par PSU ID
  • par IBAN
  • par méthode API AIS (/!\ méthode /transactions avec ou sans dateFrom / dateTo = considérée une seule et même méthode)

• Ne permet l’accès au compte que via l’IBAN du compte de paiement

• Seules les méthodes GET /accounts, PUT /consents, GET /balances, GET /transactions et GET /end-user-identity sont disponibles :
  • le mode « aisp extended_transaction_history » n’est pas supporté : la profondeur d’historique des transactions est à l’identique de celle de la banque en ligne internet fixe, soit un maximum de 62 jours pour les PRO (pas de pagination gérée par l’API), et 90 jours pour les ENT (limitation à 500 comptes, pas de pagination gérée par l’API)
  • ne permet pas de récupérer la liste des bénéficiaires de confiance d’un client (cette notion n’existe pas pour les établissements listés ci-dessous)

• Pas de gestion de la donnée optionnelle « entryReference »

Limitations liées aux segments de clientèle

Ne sont couverts par l’API que les segments clients suivants (qui sont les seuls gérés par BTP Banque) :

• Client « entreprise » et « institutionnels » ayant un accès direct à la banque en ligne « BTP NET » et un compte commençant par 08.

NB : les catégories « entreprises » (ENT) et « intitutionnels » (INSTI) couvrent les personnes morales.

Limitations liées au moyen d’authentification forte (pour l’accès banque en ligne et les API) en fonction du segment client

• ENT et ASSOC : équipement avec Mot de Passe + lecteur CAP et/ou certificat matériel TurboSign

Accès aux données de production

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

Pour accéder aux données de production, l’utilisation de l’API REGISTER est un prérequis (voir la fiche www.api.89c3.com/fr/component/bpceportal/products/522/usecases/523).

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

Le code établissement (voir ci-dessous) permettra d’adresser le bon backend via le « endpoint » www.<cdetab>.live.api.89c3.com (ou www.<cdetab>.live.api.btp-banque.fr aligné sur le nom de domaine de l’accès direct www.btp-banque.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 “Agrégation de comptes” ne peuvent être consommées que par des PSP ayant le rôle d’agrégateur (AISP). Ce statut est délivré par les autorités financières du pays dans lequel la demande est effectuée ; en France il s’agit de l’Autorité de Contrôle Prudentiel et de Résolution (ACPR), liée à la Banque de France.

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

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

PSDXX-YYYYYYYY-ZZZZZZZZ:

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

Cet identifiant OID est important à 2 titres :

• il servira à vous identifier lors des appels dans les requêtes des API STET (via le paramètre « client_id »)

• il devra être présent dans les certificats eIDAS que vous fournirez au teneur de compte (voir ci-dessous)

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

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

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

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

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

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

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