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 :

1. 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.
    
2. 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.
    
3. 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.
    
4. 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.
    
5. Vous récupérez le jeton d’accès initial pour ce client via un appel de type POST et la Banque Populaire va :
   1. Vous identifier et vous authentifier en tant que CBPII via le certificat X509 mis à disposition pour sécuriser l’échange mutuel.
   2. 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…).
       
6. 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

1. 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" ).
    
2. 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.
    
3. 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

1. Notre client (PSU) 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 (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
    
3. La Banque Populaire teneur de compte (ASPSP) va :
   1. Identifier et authentifier son client par l’une des méthodes d’authentification forte qu’elle propose et qu’il présente au client ;
   2. Effectuer des vérifications liées à votre profil en tant qu’AISP ou CBPII (validité de vos certificats QWAC et QSEALC et de votre rôle, non révocation de votre profil, etc.)
       
4. Une fois ces vérifications effectuées et si elles sont concluantes, la Banque 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.
    
5. Via un appel de type POST /token, vous allez pouvoir alors demander directement au teneur de compte votre jeton d’accès OAuth2 (access_token) avec les éléments reçus précédemment dont le code à utilisation unique.
   NB : les requêtes /token du flow Authorization Code doivent être envoyées SANS le paramètre scope.
   Voir aussi la spécification de place STET V1.4.0.47 / Part I / section 3.4.3.2 / page 22
    
6. La Banque Populaire teneur de compte (ASPSP) va :
   1. 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.)
   2. 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 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
    
8. Dès que le jeton d’accès OAuth2 (access_token) délivré par la banque a été récupéré par vos soins, vous pourrez le présenter pour pouvoir consommer les ressources de l’API.
    

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

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

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

Exemple

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

Pour plus de détail sur les données échangées, voir la rubrique « Comment tester l’API ? ».

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 devise
  • currency – 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 organisation
  • identification – obligatoire : Identifiant de l’API
  • schemeName – 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. Il y a une annotation rouge pour ceux étant définis CFONB.

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.

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

Image

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 personnas (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 :

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 :

Image

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

Roadmap

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

(*) Fonctionnalités Principales :

• Utilisation par le TPP du même endpoint que l’interface dédiée. Il dépend donc du code établissement qui permet d’adresser le bon référentiel client.
• Un paramètre de requête (header « fallback:1 » présent ou absent) ajouté par le TPP permet de distinguer une requête « Fallback » d’une requête API via l’interface dédiée qui doit être utilisée systématiquement
• Authentification du TPP via authentification mutuelle TLS par un certificat eIDAS (QWAC)
• Sécurisation identique à celle d’un accès à la banque en ligne du PSU (même interface utilisée par le PSU qu’en accès direct, et mêmes moyens d’authentification du client)
• Dans le cadre de la montée en charge de l’usage de l’interface dédiée (API), il n’est pas mis en place de bascule dynamique : la solution fallback est toujours active
• La solution de fallback est une solution de secours ne devant pas être utilisée comme moyen principal d’accès pour proposer les services DSP2. Son usage en est monitoré et tout usage abusif par un/des TPP sera automatiquement reporté auprès de l’autorité nationale compétente.

Exemple

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

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

Image

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

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

X-Request-ID: 1234

fallback: 1

User-Agent: PostmanRuntime/7.16.3

Accept: */*

Cache-Control: no-cache

Host: www.13807.live.api.banquepopulaire.fr

Accept-Encoding: gzip, deflate

Content-Length: 67

Connection: keep-alive

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

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

HTTP/1.1 302 Found

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

Location: https://www.ibps.bpgo.banquepopulaire.fr/se-connecter/sso?service=cyber&cdetab=13807&fallback=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImhF…

Content-Length: 870

Connection: close

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

</head><body>

<h1>Found</h1>

<p>The document has moved <a href= »/www.13807.live.api.banquepopulaire.fr&fallback=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImhF… »>here</a>.</p>

</body></html>

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

Pour plus de détails sur la requête POST, voir STET V1.4.2.17 / Part I / section 3.4.3

Limites

Les contraintes de cette solution sont les suivantes :

• Pas de réutilisation du contexte de l’interface dédiée, ni du jeton d’accès valable 180 jours (AISP)
• Suite à la mise en place de la nouvelle solution de banque en ligne, le fallback permet de rester sur les anciens écrans de la banque en ligne
• Seules les fonctionnalités DSP2 présentes sur la banque en ligne (référence: banque à distance sur internet fixe – pas la banque sur mobile) sont accessibles via le fallback. Par exemple, les services de banque en ligne ne proposent pas de paiement e-commerce. Cette fonctionnalité PISP n’est donc pas disponible en mode fallback
• Le client utilisateur des services (PSU) doit être connecté à l’application du TPP (pas de possibilité de traitement batch AISP pour venir récupérer les données consenties du client). La DSP2 imposant également un renforcement des moyens d’authentification forte (AF/SCA) systématique pour les accès à la banque à distance/en ligne, les moyens d’authentification fournis aux clients PSU seront utilisés (liste non exhaustive) :
  • Soft token
  • OTP SMS
  • Clé physique (pour les entreprises)

Roadmap

L’API disponibiltié des fonds fait l’objet d’améliorations et d’évolutions continues tout au long de l’année. 

Retrouvez ci-dessous notre roadmap :

Limitations fonctionnelles

Les limitations de cette API DSP2 sont les suivantes :

• S’applique à la Banque de Savoie, la Banque Palatine ainsi qu'à 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 )

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

Evolutions importantes apportées depuis la première version livrée