Vue d'ensemble
Les bénéfices attendus
Exploitons ensemble les possibilités offertes par l’ouverture des données de paiement de nos clients communs.
Ce produit API AISP DSP2 vous permet d’accéder de façon sécurisée au solde du compte du client dans le cadre d’un paiement par carte.
Accélération des services financiers
Améliore la vitesse des transactions pour une expérience utilisateur fluide et immédiate.
Amélioration de la sécurité
Renforce la sécurité des données grâce à des protocoles de protection avancés.
Facilitation de l'intégration
Permet une intégration facile avec les systèmes existants, minimisant les perturbations opérationnelles.
La connexion se fait au travers d’un dispositif sécurisé conforme aux exigences du régulateur européen.
Les différents cas d’usage possibles
Ensemble, créons de la valeur pour nos clients communs.
Vérification
Vérifiez que les fonds du client sont suffisants avant d'accepter un paiement par carte.
Comment accéder au produit ?
Pour accéder à l'API Disponibilité des fonds, les développeurs et les entreprises doivent suivre les étapes ci-dessous.
Prise de contact
Prenez contact avec les responsables Produit.
Accès
Enrôlez-vous directement depuis le processus dédié (acteurs régulés).
Intégration & Tests
Intégrez le service dans votre solution et faites-nous part de vos cas d’usage pour assurer la qualité du service.
Go Live !
Documentation
Guides
Comment réduire son risque d'impayé ?
Un de nos clients porteur de votre carte de crédit privative effectue une transaction sur un site d’e-commerce avec celle-ci. Le client a donné, au préalable, une délégation à votre établissement.
Via cette API « Disponibilité des fonds » mise à disposition par la Banque Populaire, vous pouvez demander en temps réel la confirmation que le client a suffisamment de fonds sur son compte pour couvrir le montant de cette transaction SANS lui demander ses identifiants de connexion en ligne, réduisant de fait votre exposition au risque d’impayé.
La banque répond positivement ou négativement en fonction du solde minute du client. Cependant, la banque n’effectue aucun blocage de fonds correspondant au montant de la transaction et n’enregistre pas cette transaction.
Les ressources de cette API ne peuvent être consommées que par des prestataires ayant le rôle d’émetteurs d’instruments de paiement liés à une carte (« CBPII » ou « PIISP » suivant la version STET utilisée), ce prérequis étant décrit dans voir la section « Éligibilité ».
Une fois ce prérequis rempli, le processus global est le suivant :
1- Vous avez établi un contrat avec le client, vous lui avez délivré une carte avec prélèvement domicilié dans une Banque Populaire. Il vous l’indique à travers vos interfaces.
2- Lors du premier échange avec les infrastructures du teneur de compte, vous allez faire une demande de jeton d’autorisation (et un jeton de rafraichissement). Le principe de base est, qu’en tant que TPP CBPII, vous devez obtenir ces jetons AVANT de consommer les 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 récupérer son consentement et de générer le jeton d’accès.
3- Si l’autorisation est accordée par le client, vous pourrez ensuite récupérer un jeton d’accès OAuth2 (et son jeton de rafraichissement) via des échanges sécurisés avec la plateforme BPCE API (voir le cas d’usage "Récupérez votre jeton" ).
4- En présentant ce jeton d’autorisation valable 180 jours, vous pourrez alors consommer les ressources de l’API « Disponibilité des fonds » et réduire votre risque d’impayé en interrogeant la banque sur l’existence de la provision sur le compte du client correspondant au montant du paiement (voir le cas d’usage "Vérifiez la disponibilité des fonds" ).
Au bout du délai réglementaire de 180 jours, ce processus devra être reconduit (voir le cas d’usage "Rafraichissez 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..).
Consommez l'API
Accès à l’API de vérification de la disponibilité des fonds
La cinématique ci-après décrit comment consommer l’API Disponibilité des fonds, avec la description de chaque étape, depuis la récupération du jeton jusqu’à la requête de couverture de paiement.
Etape 1 – Prérequis
Vous devez vous enrôler sur le portail BPCE API et lorsque vous souscrirez au live avec le rôle CBPII, vous devrez fournir vos certificats QWAC et QSEALC. Votre rôle CBPII sera alors vérifié sur la base des informations récupérées dans le référentiel de place (REGAFI) => validité des certificats et de votre rôle, non révocation de votre profil, etc.
Etape 2 – Autorisation d’accès en tant que CBPII qui vous est donnée par notre client connecté
Pour chacun de nos clients, vous devrez récupérer un jeton d’accès initial valable 180 jours :
- Après avoir demandé à notre client connecté sur votre application dans quelle Banque Populaire se trouvent ses comptes, vous devez soumettre une requête de récupération de votre jeton d’accès pour ce client (cf. cas d’usage "Récupérez votre jeton" ) : il s’agit d’initier la séquence de récupération du jeton d’accès OAuth2 en redirigeant notre client via son navigateur internet vers l’infrastructure informatique d’autorisation de cette Banque Populaire.
- Notre client est redirigé via son navigateur internet vers l’infrastructure informatique d’autorisation de cette Banque Populaire : une IHM mobile lui permet de s’identifier.
- Notre client procède à une authentification forte par l’une des méthodes d’authentification forte que la Banque Populaire propose et présente au client, ce qui génère un jeton d’accès.
- La banque va rediriger le client vers votre site en utilisant les URL de « call-back » (redirection) transmises précédemment ainsi que certains paramètres.
- Vous récupérez le jeton d’accès initial pour ce client via un appel de type POST et la Banque Populaire va :
- Vous identifier et vous authentifier en tant que CBPII via le certificat X509 mis à disposition pour sécuriser l’échange mutuel.
- Effectuer des vérifications liées à votre profil de CBPII (validité des certificats et de votre rôle dans le référentiel de place, non révocation de votre profil, etc…).
- Une fois ces vérifications effectuées et si elles sont concluantes, la banque va vous renvoyer une réponse HTTP 200 (OK) avec un certain nombre de données.
Dès que vous aurez récupéré le jeton d’accès OAuth2 délivré par la banque (valable 180 jours), vous pourrez le présenter pour pouvoir consommer les ressources de l’API (cf. cas d’usage "Récupérez votre jeton" ).
Etape 3 – Requête de couverture de paiement (disponibilité des fonds)
Lorsque notre client a besoin de régler un achat avec sa carte privative, vous interrogez la solvabilité du compte du client avec la méthode POST /funds-confirmations en fournissant votre jeton d’accès pour ce client (cf. cas d’usage "Vérifiez la disponibilité des fonds" ).
Etape 4 – Si le jeton de 180 jours a expiré, vous devez faire une demande de rafraîchissement du jeton pour le client
- Avec notre client connecté sur votre application, vous soumettez une requête de rafraîchissement du jeton pour ce client (cf. cas d’usage "Rafraîchissez votre jeton" ).
- Notre client est redirigé vers une IHM mobile de sa Banque Populaire et procède à une authentification forte dans cette IHM mobile, ce qui réactive le jeton d’accès.
- Vous récupérez le jeton rafraîchi pour ce client.
Publications réglementaires
Récupérez 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 OAuth2.
Cinématique de récupération du jeton d’autorisation
- Notre client (PSU) vous indique l’identité de sa Banque Populaire teneur de compte.
- 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 Populaire teneur de compte (ASPSP) et en utilisant la commande :
GET /authorize.
Voir aussi la spécification de place STET V1.4.0.47 / Part I / section 3.4.3.2 / page 21
- La Banque Populaire 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.)
- Une fois ces vérifications effectuées et si elles sont concluantes, la Banque Populaire 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 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.
- 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/tokendu flow Authorization Code doivent être envoyées SANS le paramètrescope.
Voir aussi la spécification de place STET V1.4.0.47 / Part I / section 3.4.3.2 / page 22
- La Banque Populaire 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.
- Une fois ces vérifications effectuées et si elles sont concluantes, la Banque Populaire 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.0.47 / Part I / section 3.4.3.2 / page 23
- 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
Schéma du principe de récupération du jeton d’accès OAuth2
En tant que développeur d’une application désirant utiliser cette API, l’obtention d’un jeton d’accès OAuth2 vous est nécessaire et se fait grâce au processus suivant :
Références
- Section 3.4.3.2 de la spécification STET v1.4.0.47 : https://www.stet.eu/en/psd2/
- OAuth 2.0 Authorization Framework : https://tools.ietf.org/html/rfc6749#section-4.1
Développement pas à pas
1. Le client vous indique l’identité de sa Banque Populaire 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 Populaire teneur de compte, le détail des liens et des paramètres se trouvent ci-après:
Voir aussi [STET Framework page 21]
GET /authorize?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope={scope}[&state={state}]
| Nom | Description | Type | |
|---|---|---|---|
| response_type | [1..1] | Type de jeton attendu | Chaîne [10] => doit être renseignée avec le « code » |
| client_id | [1..1] | Votre identification en tant que TPP | Chaîne[34] => doit être égale à la partie « OrganizationIdentifier » du « Distinguished Name » du certificat eiDAS, en accord avec la spécification ETSI |
| redirect_uri | [0..1]
[1..1] | URL de re-routage vers votre application | Chaîne [140] > champ obligatoire pour les Banques Populaires |
| scope | [0..1] | Spécifie les accréditations génériques sur lesquelles notre client et vous, vous vous êtes accordés :
Pour un AISP :
Pour un CBPII :
| Chaîne [140] => les espaces délimitent la liste des rôles |
| state | [0..1] | Etat interne qui peut être utilisé par vous pour gérer le contexte | Chaîne [34] |
3. La Banque Populaire 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 Populaire 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 lorsque vous remplirez le formulaire de souscription pour le live sur le portail BPCE API.
Voir aussi [STET Framework page 22]
| Nom | Description | Type | |
|---|---|---|---|
| code | [1..1] | Code court utilisé pour récupérer le jeton d’accès | Chaîne [34] |
| state | [0..1] | Etat interne si fourni par vous | Chaîne [34] |
5. Vous allez pouvoir alors demander directement à la Banque Populaire le jeton d’accès OAuth2 via un appel de type POST envoyé avec les paramètres suivants :
Voir aussi [STET Framework page 22]
| Nom | Description | Type | |
|---|---|---|---|
| grant_type | [1..1] | Type d’autorisation requise | Chaîne [34] => doit être renseignée avec le « authorization code » |
| code | [1..1] | Code court fourni précédemment par l’ ASPSP | Chaîne [34] |
| redirect_uri | [1..1] | URL de re-routage du TPP | Chaîne [140] => doit être égale au redirect_uri fournie dans la requête GET /token. |
| client_id | [1..1] | Identification du TPP | Chaîne [34] => doit être égale à la partie « OrganizationIdentifier » du « Distinguished Name » du certificat eiDAS, en accord avec la spécification ETSI |
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 Populaire 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 Populaire va vous renvoyer une réponse HTTP 200 (OK) qui contiendra les données suivantes:
Voir aussi [STET Framework page 23]
| Nom | Description | Type | |
|---|---|---|---|
| access_token | [1..1] | Jeton d’accès fourni par l’ASPSP au TPP | Chaîne [140] |
| token_type | [1..1] | Type du jeton d’accès fourni (« Bearer » or « MAC ») | Chaîne [10] => doit être renseignée avec « Bearer » |
| expires_in | [0..1] | Durée de vie du jeton, en secondes. Le jeton peut être utilisé plusieurs fois tant qu’il n’a pas expiré. | Numérique |
| refresh_token | [0..1] | Jeton de rafraîchissement qui peut être utilisé dans le cas d’une future requête de renouvellement de jeton. | Chaîne [140] |
Exemple
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { « access_token » : « 2YotnFZFEjr1zCsicMWpAA », « token_type » : « example », « expires_in » : 3600, « refresh_token » : « tGzv3JOkF0XG5Qx2TlKWIA » }
8. Dès que le jeton d’accès OAuth2 délivré par la Banque Populaire (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
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.
Pour plus de détails sur les données échangées, voir la rubrique "Testez l'API avec la sandbox".
Vérifiez la disponibilité des fonds
Cas d’usage
Ce service permet de vérifier la disponibilité des fonds pour le compte à vue de notre client pour un montant donné.
Prérequis
Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité, d’avoir récupéré le jeton d’accès OAuth2 (voir le cas d’usage « Récupérez votre jeton« ) et de fournir les paramètres du body.
Requête
POST /funds-confirmations
Paramètres du body requis pour l’appel de ce service
paymentCoverageRequestId– obligatoire : Identifiant de la requête de paiement
payee– facultatif : Le commerçant chez qui la carte est acceptée et donnant des informations sur le PSU
instructedAmount– obligatoire : La structure comprenant le montant renseigné ainsi que la devisecurrency– obligatoire : Devise du montant renseignéamount– obligatoire : Montant qui permettra de déterminer si les fonds sont disponibles
accountId– obligatoire : Identifiant unique pour le compte renseigné.iban– facultatif : Numéro de compte bancaire international (IBAN)other– facultatif : Identifiant unique d’un compte, d’une personne ou organisationidentification– obligatoire : Identifiant de l’APIschemeName– obligatoire : Type d’identifiant (BANK, COID, SREN, SRET, NIDN, OAUT, CPAN)issuer– facultatif : Entité fournissant l’identification
Résultat retourné
Le résultat retourné reprendra les informations de la requête ainsi que la réponse concernant la disponibilité des fonds sous la forme d’un booléen.
Un lien self sera également présent pour revenir à la page obtenue juste après exécution de la requête.
Exemple
Requête
POST http://localhost:8080/v1/funds-confirmations
{
« paymentCoverageRequestId » : « MyCoverage123456 »,
« instructedAmount » : {
« currency » : « EUR »,
« amount » : « 123.45 » },
« accountId » : { « iban » : « FR7613807008043001965405255 » }
}
Résultat
Status code : 200
Body
{ « result »: true, « request »: { « accountId »: { « iban »: « FR7613807008043001965405255 » }, « paymentCoverageRequestId »: « MyCoverage123456 », « instructedAmount »: { « amount »: « 123.45 », « currency »: « EUR » } }, « _links »: { « self »: { « href »: « https://www.rs-sandbox.api.89c3.com/stet/psd2/v1/funds-confirmations » } }}
(cas du persona Marc -D0999990I0)
Codes erreurs
Voici la liste de descriptions des codes erreurs de ce service.
| Erreur | Description de l’erreur |
|---|---|
| AC01 (CFONB) | IncorrectAccountNumber : le numéro de compte est incorrect ou inconnu |
| AC04 (CFONB) | ClosedAccountNumber : le compte est clos |
| AC06 (CFONB) | BlockedAccount : le compte est bloqué / fait l’objet d’une opposition |
| FF01 (CFONB) | InvalidFileFormat => le body ne respecte le format définit par la norme STET |
| BADS | BadScope : l’appel au service a été fait avec un jeton AISP (CBPII attendu) |
| INTE | InternalError : il y a une erreur interne de traitement |
| INTS | InternalServerError : il y a une erreur interne de communication avec le SI |
| NGAC | NotGrantedAccount : le compte n’est pas consenti |
| NIMP | NotImplemented : le mauvais verbe est appelé (POST attendu) |
| TMRQ | TooManyRequest : le nombre de requêtes possibles a été dépassé |
| IPSU | InvalidPSU : numéro d’abonné non référencé ou abonnement banque à distance résilié |
Tests d’acceptance
Ces cas de tests ont pour objectif de vous permettre d’effectuer un minimum de tests pour prendre en main cette API et y accéder depuis votre application.
| Description du test | Jeu de données |
|---|---|
| Cas standard, le paiement peut être couvert | Persona : Marc -D0999990I0 Prérequis : scope OAuth2 = piisp Amount : montant inférieur à 459€ accountId : FR7613807008043001965405255 Currency : EUR Résultat : réponse positive à la requête :
|
| Cas aux limites : le paiement ne peut être couvert en raison de fonds insuffisants | Persona : Marc -D0999990I0 Prérequis : scope OAuth2 = piisp Amount : montant supérieur à 4 179€ accountId : FR7613807008043001965405158 Currency : EUR Résultat : réponse négative à la requête :
|
| Requête HTTP utilisant la méthode GET | Persona : Marc -D0999990I0 Prérequis : scope OAuth2 = piisp Résultat : réponse HTTP code 405 => méthode non autorisée |
| Requête HTTP avec un IBAN absent ou erroné en paramètre du body | Persona : Marc -D0999990I0 Prérequis : scope OAuth2 = piisp Amount : montant de 4 179€ accountId : FRXXXX807008043001965405158 Currency : EUR Résultat : réponse HTTP code 400 => requête erronée message d’erreur : AC01 |
| Requête HTTP avec une structure de montant/devise absente ou erronée en paramètre du body | Persona : Marc -D0999990I0 Prérequis : scope OAuth2 = piisp accountId : FR7613807008043001965405158 Résultat : réponse HTTP code 400 => requête erronée message d’erreur : FF01 |
| Requête HTTP avec un montant absent ou erroné en paramètre du body | Persona : Marc -D0999990I0 Prérequis : scope OAuth2 = piisp accountId : FR7613807008043001965405158 Currency : EUR Résultat : réponse HTTP code 400 => requête erronée message d’erreur : FF01 |
| Requête HTTP avec une devise absente ou erronée en paramètre du body | Persona : Marc -D0999990I0 Prérequis : scope OAuth2 = piisp Amount : montant supérieur à 4 179€ accountId : FR7613807008043001965405158 Résultat : réponse HTTP code 400 => requête erronée message d’erreur : FF01 |
| Requête HTTP avec un identifiant de requête de paiement absent ou erroné en paramètre du body | Persona : Marc -D0999990I0 Prérequis : scope OAuth2 = piisp Amount : montant supérieur à 4 179€ accountId : FR7613807008043001965405158 Currency : EUR Résultat : réponse HTTP code 400 => requête erronée message d’erreur : FF01 |
Rafraîchissez 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 Populaire 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 Populaire.
2. La Banque Populaire 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 Populaire invalide l’ancien jeton d’autorisation.
Exemple
Un exemple de requête est fourni dans la rubrique « Testez l'API avec la sandbox ».
Pour plus de détails sur les données échangées, voir la rubrique « Récupérez votre jeton ».
Testez l'API avec la sandbox
Schéma Sandbox
La sandbox BPCE API peut être utilisée directement via votre application en appelant l’API "Disponibilité des fonds" de la plateforme BPCE-API (assemblage sandbox).
En assemblage sandbox, il y a 2 appels :
- Le premier pour récupérer le jeton d’autorisation.
- Le second pour faire l’appel à l’API "Disponibilité des fonds".
Explications
Votre application consommatrice de l’API "Disponibilité des fonds" de la sandbox va devoir récupérer un jeton d’accès via sa clé d’authentification auprès de l’AS (Authentification Server).
Ainsi l’application pourra consommer la méthode POST /funds-confirmations grâce à son jeton d’accès.
Les données utilisées pour faire les tests seront issues des persona (voir le cas d’usage "Testez nos persona" ), ce qui permettra de choisir des profils spécifiques selon les tests de façon à mieux appréhender les résultats obtenus.
Testez nos persona
Cette page présente les jeux de données qui permettent de tester l’API :
- Des clients fictifs sont proposés par segment de clientèle (étudiant, cadre, entreprise, etc.)
- Les caractéristiques de leurs comptes et cartes à débit différé y sont déclinées (mono-compte, multi-comptes, multi-bancarisé, solde du compte)
- Les données utiles attendues en entrée par les API y sont énumérées (identifiant banque à distance, code SMS pour les authentifications fortes, IBAN)
| Persona | Segment | Identifiant banque à distance | Code établissement | Code SMS pour authentification | IBAN | Numéro de compte- accountId | Compte à vue | Solde – balance | Devise – currency |
|---|---|---|---|---|---|---|---|---|---|
| Marc | Cadre | D0999990I0 | 13807 | 12345678 | FR7613807008043001965405158 | 038-CPT30019654051 | A vue | 4 348.95 | EUR |
| FR7613807008043001965405255 | 038-CPT30019654052 | A vue | 459.56 | EUR | |||||
| FR7613807008043001965405352 | 038-CPT30019654053 | A vue | 2 165.50 | EUR | |||||
| Marie | Retraite | D0999991I0 | 13807 | 12345678 | FR7613807008043001965406128 | 038-CPT30019654061 | A vue | 1 754.03 | EUR |
| FR7613807008043001965406225 | 038-CPT30019654062 | A vue | 11 429.00 | EUR | |||||
| Thomas | Etudiant | D0999980 | 13807 | 12345678 | FR7613807008043001965407195 | 038-CPT30019654071 | A vue | 749.27 | EUR |
| FR7613807008043001965407292 | 038-CPT30019654072 | A vue | -20 000.00 | EUR | |||||
| Alix | Cadre | D0999992I0 | 13807 | 12345678 | FR7613807008043001965408165 | 038-CPT30019654081 | A vue | 52.00 | EUR |
| FR7613807008043001965408262 | 038-CPT30019654082 | A vue | 395.45 | EUR | |||||
| FR7613807008043001965408359 | 038-CPT30019654083 | A vue | 298.19 | EUR | |||||
| Tech’n Co | Entreprise | D0999993I0 | 13807 | 12345678 | FR7613807008043001965409135 | 038-CPT30019654091 | A vue | 63 917.00 | EUR |
| Adam | Entrepreneur | D0999994I0 | 13807 | 12345678 | FR7613807008063031966574122 | 038-CPT30319665741 | A vue | 0.00 | EUR |
| FR7613807008063031966574219 | 038-CPT30319665742 | A vue | -2 894.05 | EUR | |||||
| Lea | Cadre | 755238649 | 13807 | 12345678 | FR7617515000920400430518020 | 038-CPT04004305180 | A vue | -150.00 | EUR |
Marc 42 ans – Nantes Célibataire – Cadre dans la fonction publique – 18 ans d’expérience 3 comptes à vue Sa vie / Son Histoire / Son travail
Ses buts
| Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Marie 73 ans – Nantes Mariée – Retraitée du secteur privée 2 comptes à vue Sa vie / Son Histoire / Son travail
Ses buts
| Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Thomas 21 ans – Nantes Etudiant – Ecole d’ingénieur informatique privée 2 comptes à vue Sa vie / Son Histoire / Son travail
Ses buts
| Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Alix 32 ans – Nantes Mariée – 3 enfants Cadre – Employé du secteur privé 3 comptes à vue Sa vie / Son Histoire / Son travail
Ses buts
| Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Tech’n Co Créée par Dominique – Nantes 37 ans – Mariée – 2 enfants 1 compte à vue Sa vie / Son Histoire / Son travail
Ses buts
| Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Adam 29 ans – Montpellier Célibataire – Entrepreneur – 4 ans d’expérience 2 comptes à vue Sa vie / Son Histoire / Son travail
Ses buts
| Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Léa 35 ans – Lyon Mariée – Cadre chez un assureur – 10 ans d’expérience 1 compte à vue Sa vie / Son Histoire / Son travail
Ses buts
| Son utilisation
Les freins, frustrations potentielles
Ce qui peut l’influencer
La bonne surprise
|
Utilisez le fallback
Principe
Conformément à la réglementation, les établissements du Groupe BPCE ont mis en place une interface dédiée aux prestataires de services de paiement : il s’agit des API REST DSP2 publiées.
Si les API DSP2 exposées sont défaillantes, le prestataire des services de paiements pourra utiliser la solution couvrant les « mesures d’urgence applicables à une interface dédiée » (ou « fallback ») dont le principe est le suivant :
Cette solution répond aux exigences règlementaires de la DSP2 (article 33 des RTS). Vous pourrez l’utiliser avec les mêmes conditions et pré-requis décrits dans la rubrique "Eligibilité" .
Roadmap
Retrouvez ci-dessous les éléments de notre trajectoire prévisionnelle :
Version |
Fonctionnalités | Sandbox Date de déploiement BPCE API Dev Portal & Sandbox | Live Date de déploiement BPCE Live API Gateway |
|---|---|---|---|
| v1.0 | Fallback (*) | Non applicable | Fin Septembre 2019 |
(*) Fonctionnalités Principales :
- Utilisation par le TPP du même endpoint que l’interface dédiée. Il dépend donc du code établissement
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>.oba-bad-me-live.api.89c3.com/stet/psd2/oauth/token (nouvelle url à prendre en compte dès à présent)
(Pour rappel, l’url 89C3 existante www.<codetab>.live.api.89C3.com ne sera plus disponible à partir du 28/09/2025)
avec par exemple <codetab> =
- 13807 pour BPGO
- 10548 pour Banque de Savoie
- 40978 pour Banque Palatine
avec :
- son certificat eIDAS QWAC de production
- le paramètre header (fallback: "1")
POST /stet/psd2/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
X-Request-ID: 1234
fallback: 1
User-Agent: PostmanRuntime/7.16.3
Accept: */*
Cache-Control: no-cache
Host: www.13807.live.api.banquepopulaire.fr
Accept-Encoding: gzip, deflate
Content-Length: 67
Connection: keep-alive
client_id=PSDFR-ACPR-12345&grant_type=client_credentials&scope=aisp
2. Si les vérifications sont positives, nous allons vous renvoyer dans le header une url de type à utiliser dans le cadre de la redirection vers l’environnement de la banque en ligne, et qui contient un jeton JWT (champs « &fallback= ») qui doit être aussi utilisé dans ce cadre :
HTTP/1.1 302 Found
Date: Tue, 25 May 2021 21:46:59 GMT
Location: https://www.ibps.bpgo.banquepopulaire.fr/se-connecter/sso?service=cyber&cdetab=13807&fallback=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImhF…
Content-Length: 870
Connection: close
Content-Type: text/html; charset=iso-8859-1
</head><body>
<h1>Found</h1>
<p>The document has moved <a href= »/www.13807.live.api.banquepopulaire.fr&fallback=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImhF… »>here</a>.</p>
</body></html>
3. Une fois redirigé, le TPP doit utiliser ensuite les identifiants du PSU via sa méthode propriétaire
Pour plus de détails sur la requête POST, voir STET V1.4.2.17 / Part I / section 3.4.3
Limites
Les contraintes de cette solution sont les suivantes :
- Pas de réutilisation du contexte de l’interface dédiée, ni du jeton d’accès valable 180 jours (AISP)
- Suite à la mise en place de la nouvelle solution de banque en ligne, le fallback permet de rester sur les anciens écrans de la banque en ligne.
- Seules les fonctionnalités DSP2 présentes sur la banque en ligne (référence: banque à distance sur internet fixe – pas la banque sur mobile) sont accessibles via le fallback. Par exemple, les services de banque en ligne ne proposent pas de paiement e-commerce. Cette fonctionnalité PISP n’est donc pas disponible en mode fallback.
- Le client utilisateur des services (PSU) doit être connecté à l’application du TPP (pas de possibilité de traitement batch AISP pour venir récupérer les données consenties du client). La DSP2 imposant également un renforcement des moyens d’authentification forte (AF/SCA) systématique pour les accès à la banque à distance/en ligne, les moyens d’authentification fournis aux clients PSU seront utilisés (liste non exhaustive) :
- Soft token
- OTP SMS
- Clé physique (pour les entreprises)
Roadmap
L’API Disponibilité des fonds fait l’objet d’améliorations et d’évolutions continues tout au long de l’année.
Retrouvez ci-dessous notre roadmap :
Version de l’API |
Version de la norme STET |
Fonctionnalités | Sandbox Deployment date BPCE API Dev Portal & Sandbox | Live Deployment date BPCE Live API Gateway |
|---|---|---|---|---|
| v1.0 | v1.4.0.47 | Vérifier la disponibilité des fonds | 14 mars 2019 | septembre 2019 |
Limitations fonctionnelles
Les limitations de cette API DSP2 sont les suivantes :
- S’applique à toutes les Banques Populaires exceptée la BRED
- Ne s’applique qu’aux comptes de paiements actifs et accessibles en ligne (cf. texte de la Directive DSP2) => l’interrogation du solde ne pourra se faire que pour un compte à vue.
- N’utilise que le mode d’authentification par redirection (Authentification Forte du client demandée et gérée via la banque).
- Ne bloque / ne réserve pas les fonds.
- Ne permet l’accès aux données que via l’IBAN (champ [iban] ) du compte à vue => les Banques Populaires ne connaissent pas les références de vos cartes privatives.
Limitations sur les données
La liste des établissements bancaires actuellement accessibles pour cette API est détaillée ci-dessous. Le code établissement (<cdetab>) vous permet d’adresser le bon référentiel client via un « endpoint » au format www.<cdetab>.oba-bad-me-live.api.89c3.com (nouvelle url à prendre en compte dès à présent).
(Pour rappel, l’url 89C3 existante www.<codetab>.live.api.89C3.com ne sera plus disponible à partir du 28/09/2025)
Exemples :
- STET V1.4.0 POST https://www.16807.oba-bad-me-live.api.89c3.com/stet/psd2/v1/funds-confirmations ( /!\ scope = piisp )
- STET V1.4.2 POST https://www.16807.oba-bad-me-live.api.89c3.com/stet/psd2/v1.4.2/funds-confirmations ( /!\ scope = cbpii )
| Code établissement | Nom de l’établissement | Nom abrégé |
|---|---|---|
| 10807 | B.P Bourgogne Franche Comté | BPBFC |
| 16807 | B.P AUvergne et Rhône-Alpes | BPAURA |
| 10207 | B.P RIves de Paris + BICS | BPRI |
| 18707 | B.P Val de France | BPVF |
| 13507 | B.P du Nord | BPN |
| 16607 | B.P Sud | BPS |
| 10907 | B.P Aquitaine Centre Atlantique | BPACA |
| 14707 | B.P Alsace Lorraine Champagne | BPALC |
| 17807 | B.P OCcitane | BPOC |
| 10907 | Crédit Maritime Littoral du Sud Ouest | CMSOU |
| 13807 | B.P Grand Ouest | BPGO |
| 13807 | Crédit Maritime Grand Ouest | CMMGO |
| 14607 | B.P Méditerranée | BPMED |
| 16607 | Crédit Maritime Méditerranée | CMMMED |
| 10548 | Banque de SAVoie | BQSAV |
| 40978 | Banque Palatine | BPAL |
Eligibilité
Les ressources de cette API ne peuvent être consommées que par des PSP ayant le rôle « CBPII » ou « PIISP » suivant la version STET utilisée. 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.
De plus, vous devez disposer 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 le portail du Groupe BPCE, vous aurez à nous transmettre vos certificats QWAC et QSEALC :
- de production pour le fonctionnement de l’assemblage en sandbox
- de production lors des appels sur notre passerelle BPCE API Live
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 ).
Historique
Historique des versions
Cette API est conforme à la spécification STET (https://www.stet.eu/en/psd2/) afin de répondre aux exigences règlementaires de la DSP2. Elle tient compte des limitations fonctionnelles propres aux Banques Populaires.
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é compé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 est le 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.
Planning des évolutions à venir de l’API
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 :
Versionning de l’API
| Version de notre API | Version norme STET |
|---|---|
| v1.0 | v1.4.0.47 |
Evolutions importantes apportées depuis la première version livrée
| Methode(s) | Date d’effet | Description de l’évolution |
|---|---|---|
| GET /fundsConfirmation | 17 mai 2019 | Documentation portail : ajout de précisions sur le caractère obligatoire ou facultatif des paramètres et des champs de la requête. |
| Eligibilité | 1er octobre 2019 | Documentation portail :
|