Initier un paiement
Un de nos clients effectue une transaction sur un site d’e-commerce ou souhaite effectuer un virement de compte à compte (externe).
Via cette API « Initiation de paiement » mise à disposition par l’APSPS, vous pouvez soumettre en temps réel une demande d’initiation du paiement qui se traduira au final par un virement.
Le client connecté va être sollicité par sa banque pour valider l’opération.
Dans le cadre d’un parcours classique :
- Le PSU s’identifie et s’authentifie
- Puis, il sélectionne le compte de paiement disposant d’un solde suffisant pour le montant de l’opération
- Enfin, la banque scelle l’opération après que le client se soit à nouveau authentifié fortement pour valider l’opération
Dans le cadre d’un parcours fluide, les données du compte débiteur sont transmises dans la requête d’initiation de paiement :
- Le PSU s’identifie si son identifiant n’est pas transmis dans la requête
- Puis, il vérifie les informations de l’opération
- Enfin, la banque scelle l’opération après que le client se soit authentifié fortement pour valider l’opération
Cette API ne peut être consommée que par des prestataires ayant le rôle d’initiateurs de paiement (« PISP »), ce prérequis étant décrit dans voir la rubrique « Éligibilité« .
Une fois ce prérequis rempli, le processus global est le suivant :
1- Le client souhaite utiliser les services d’un TPP afin de réaliser un virement ou un transfert, ou alors il sélectionne votre service lorsqu’il est sollicité par un e-commerçant pour régler son achat sur le site du e-commerçant. Il précise, à travers les interfaces du TPP, le teneur de compte (ASPSP) dans lequel il est domicilié.
2- Lors du premier échange avec les infrastructures du teneur de compte, le TPP effectue une demande de jeton d’autorisation. Le principe de base est, qu’en tant que initiateur de paiements PISP, le TPp doit obtenir ce jeton AVANT de consommer l’API. Ce jeton est généré par le teneur de compte (ASPSP) APRES avoir identifié le TPP.
3- Si le teneur de compte a pu vérifier l’identité et les agréments du prestataire, il pourra ensuite récupérer un jeton d’accès OAUTH2 via des échanges sécurisés avec la plateforme BPCE API (voir la rubrique « Vue d’ensemble » > « Récupérer votre jeton« ).
4- En présentant ce jeton d’autorisation valable uniquement pour cette opération, le TPP pourra alors consommer l’API « initiation de paiement » afin :
- D’initier le paiement (voir la rubrique « Cas d’usage » > « Initier un paiement« )
- De récupérer le statut de l’initiation de paiement (voir la rubrique « Cas d’usage » > « Obtenir le statut« ) ;
- De modifier une initiation de paiement (voir la rubrique « Cas d’usage » > « Annuler une initiation« )
- De confirmer une initiation de paiement (voir la rubrique « Cas d’usage » > « Confirmer une initiation« ).
Consommer l'API
La description des services proposés ci-après n’est que purement fonctionnelle. Les aspects techniques sont répertoriés dans les sections « Cas d’usage » qui sont plus détaillées.
Vous devez aussi être familier avec la terminologie DSP2 et les abréviations utilisées. Vous pouvez également utiliser la foire aux questions (FAQ), l’assistant virtuel ou le glossaire.
Prérequis
En tant que TPP, vous devez être accrédité par l’autorité de contrôle prudentiel et de résolution (l’ACPR en France) pour le rôle d’initiateur de paiement (« PISP »).
Pour accéder aux services de l’API d’initiation de paiement, le TPP doit récupérer un jeton d’accès OAUTH2 délivré par l’établissement bancaire du PSU.
A ce titre, le TPP doit s’authentifier mutuellement avec le teneur de compte (ASPSP) par échange de certificats eIDAS QWAC.
Le TPP présentera ensuite ce jeton d’accès OAUTH2 pour pouvoir consommer les services de l’API d’initiation de paiement.
Initier un paiement
Il existe deux cas d’utilisation de l’API d’initiation de paiement :
1) Le PISP fait une demande de paiement pour le compte d’un commerçant car le client PSU achète des biens ou des services sur un site e-commerce.
Il existe un contrat entre le e-commerçant et le PISP.
Le e-commerçant transmet les caractéristiques du paiement demandées au TPP PISP et redirige le client PSU vers le portail du PISP.
Le PISP interroge le client PSU pour connaître l’établissement bancaire à partir duquel il souhaite débiter son compte. Puis il prépare la demande de paiement et l’envoie à l’établissement bancaire du client.
Le bénéficiaire (= le e-commerçant) est indiqué dans le paiement.
2) Le PISP fait une demande de virement unitaire ou multiple pour le compte du client PSU titulaire du compte. Le PSU fournit au PISP les informations nécessaires au transfert.
Le PISP interroge le client PSU afin de connaître l’établissement bancaire à partir duquel il souhaite débiter son compte. Puis il prépare la demande de paiement et l’envoie à l’établissement bancaire du PSU.
voir les spécifications STET V1.6.2 / Part I
Le TPP transmet la requête d’initiation de paiement via la méthode POST /payment-requests (cf. rubrique « Cas d’usage » > « Initier un paiement« ).
La méthode d’authentification supportée par l’établissement bancaire est le mode REDIRECT renforcé :
1) Le PSU est redirigé vers un écran d’identification proposé par son établissement bancaire et dans lequel il saisira son identifiant de banque à distance.
2) Le PSU est redirigé vers un premier écran d’authentification forte proposé par son établissement bancaire pour valider son identité.
La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du PSU par l’établissement bancaire (SMS OTP, Secur’pass, etc.).
Elle dépend aussi de l’équipement du PSU sur lequel tourne l’application du PISP utilisée par le PSU (PC ou mobile/tablette).
3) Le PSU est redirigé vers un écran de sélection de son compte à débiter proposé par son établissement bancaire.
4) Le PSU sélectionne et valide le compte à débiter.
5) Le PSU est redirigé vers un second écran d’authentification forte proposé par son établissement pour valider son paiement.
La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du PSU par l’établissement bancaire (SMS OTP, Secur’pass, etc.).
Elle dépend aussi de l’équipement bancaire du PSU sur lequel tourne l’application du PSU (PC ou mobile/tablette).
6) Le PSU est redirigé vers un écran de confirmation de l’opération proposé par son établissement bancaire.
7) Le PSU est redirigé vers l’application du PISP.
8) Vous transmettez la requête de confirmation de l’initiation du paiement via la méthode POST /payment-requests/{paymentRequestResourceId}/confirmation (cf. rubrique « Cas d’usage » > « Confirmer une initiation de paiement« ), ce qui déclenche la prise en compte du paiement par l’établissement bancaire.
Si le PISP fournit l’IBAN du PSU à débiter dans sa requête, le parcours client est simplifié (« parcours PISP fluide ») :
1) Le PSU est redirigé vers un écran de confirmation du virement unitaire ou multiple(cette fonctionnalité sera disponible en février 2023) dans lequel seul le compte correspondant à l’IBAN du PSU est proposé au PSU.
3) Le PSU valide l’opération.
4) Le PSU est redirigé vers un écran d’identification et d’authentification forte proposé par son établissement pour valider son paiement.
La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du PSU par l’établissement bancaire (SMS OTP, Secur’pass, etc.).
Elle dépend aussi de l’équipement bancaire du PSU sur lequel tourne l’application du PSU (PC ou mobile/tablette).
5) Le PSU est redirigé vers un écran de confirmation de l’opération proposé par son établissement bancaire.
6) Le PSU est redirigé vers l’application du PISP.
7) Vous transmettez la requête de confirmation de l’initiation du paiement via la méthode POST /payment-requests/{paymentRequestResourceId}/confirmation (cf. rubrique « Cas d’usage » > « Confirmer une initiation de paiement« ), ce qui déclenche la prise en compte du paiement par l’établissement bancaire.
Le PISP fournit lors de sa demande d’initiation une ou deux URL call back :
- La première sera appelée par l’établissement bancaire dans le cas où la demande d’initiation est traitée et si le PSU a donné son consentement pour le paiement.
- La seconde URL call back sera utilisée par l’établissement bancaire en cas de refus du consentement. Cette seconde URL est facultative : la première URL de call back sera utilisée si la seconde n’est pas renseignée.
Le PISP peut renseigner un indicateur lui permettant d’indiquer qu’il considère la demande de paiement comme étant un cas d’exemption de SCA. La décision finale d’appliquer ou non une SCA reste à l’ASPSP : à ce jour aucune exemption n’est acceptée parmi les cas de dérogations à l’obligation d’authentification forte du PSU, si les exigences générales en matière d’authentification sont remplies, telles que décrits dans l’article 2 des RTS de la DSP2.
Récupérer le statut d’une initiation du paiement
Vous récupérez le statut d’une initiation de paiement via la méthode GET /payment-requests/{paymentRequestResourceId} (cf. rubrique « Cas d’usage » > « Récupérer le statut d’une initiation de paiement« ).
Cet appel vous permet de récupérer l’ensemble des données de l’initiation de paiement enrichies du resourceId et des statuts de l’initiation et du ou des paiements qu’elle contient.
Les données sont accessibles pendant 35 jours.
Annuler une initiation de Paiement
Pour un virement unitaire différé qui n’a pas encore été exécuté ou pour un virement unitaire SCT permanent dont la dernière échéance n’a pas été atteinte, le TPP peut annuler une initiation de paiement via la méthode PUT /payment-requests/{paymentRequestResourceId}(cf. rubrique « Cas d’usage » > « Annuler une initiation de paiement« )
La méthode d’authentification supportée par l’établissement bancaire est le mode REDIRECT :
1) Le PSU est redirigé vers un écran d’identification proposé par son établissement bancaire et dans lequel il saisira son identifiant de banque à distance.
2) Le PSU est redirigé vers un écran d’authentification forte proposé par son établissement bancaire pour valider son identité.
3) Le PSU est redirigé vers un écran récapitulatif de l’opération en cours d’annulation proposé par son établissement bancaire.
4) Le PSU valide l’annulation de l’initiation du paiement.
5) Le PSU est redirigé vers un écran de confirmation de l’opération proposé par son établissement bancaire.
6) Le PSU est redirigé vers l’application du TPP PISP.
Le PISP fournit lors de sa demande d’annulation une ou deux URL de call back :
La première sera appelée par l’établissement bancaire dans le cas où la demande d’annulation est traitée et si le PSU a donné son consentement pour cette annulation d’opération.
La seconde URL sera utilisée par l’établissement bancaire en cas de refus du consentement ou de problème. Cette seconde URL est facultative : la première URL call back sera utilisée si la seconde n’est pas renseignée.
Confirmer une initiation de paiement
Vous confirmez une initiation de paiement via la méthode POST /payment-requests/{paymentRequestResourceId}/confirmation, approche REDIRECT renforcé (voir la rubrique « Cas d’usage » > « Confirmer une initiation de paiement« ).
Par contre, le service de confirmation d’une annulation de demande de paiement ne sera pas supporté. L’annulation sera effective dès l’acceptation de la demande.
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 :
| Version | Fonctionnalités | Sandbox
Date de déploiement BPCE API Dev Portal & Sandbox |
Live
Date de déploiement BPCE Live API Gateway |
| toute version API DSP2 | Fallback (*) | Non applicable | Fin Septembre 2019 |
(*) 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
Content-Length: 870
Connection: close
Content-Type: text/html; charset=iso-8859-1
</head><body>
<h1>Found</h1>
<p>The document has moved <a >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 (webview dans l’app mobile bancaire) s’activera en production après l’envoi d’une série classique de requêtes par l’app du TPP au format STET suivant par exemple pour la Caisse d’Epargne :
- App2App activée via url de redirection fournie par l’ASPSP www.<codetab>.live.api.caisse-epargne.fr/89C3api/accreditation/v2/…
Sinon, une webview sur le navigateur du smartphone du client sera affichée 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é www.<codetab>.live.api.89c3.com/stet/psd2/oauth/token(ce qui peut être utile comme backup en cas de problème avec l’App2App)
Assemblage Sandbox
Introduction – précisions sur les fonctionnalités de la sandbox
La sandbox BPCE API peut être utilisée directement via l’application du TPP en appelant l’API « Initiation de paiement » de la plateforme BPCE API.
En assemblage sandbox, il y a deux types d’appel :
- Le premier pour récupérer le jeton d’autorisation (voir la rubrique « Vue d’ensemble » > « Récupérez votre jeton« ) ;
- Le second pour faire l’appel à l’API DSP2 « Initiation de paiement » (voir les cas d’usage « Initier un paiement« , « Récupérer le statut « , « Confirmer une initiation » et « Annuler une initiation »).
Limitations en environnement sandbox :
- Le cas d’usage « Annuler une initiation de paiement », n’est pas totalement testable dans l’environnement sandbox car cette méthode nécessite un croisement des données dynamiques alors que notre sandbox a un comportement statique
- En conséquence, les requêtes d’annulation d’une initiation de paiement sont acceptées dès que le format de la requête est correct (l’identifiant de l’initiation de paiement étant supposé exister).
L’application du TPP consommatrice de l’API « Initiation de paiement » en assemblage sandbox va devoir récupérer un jeton d’accès via sa clé d’authentification auprès de l’AS (Authentification Server).
Ainsi l’application TPP pourra consommer les méthodes « POST /payment-requests« , « GET /payment-requests/{paymentRequestRessourceId}« , « POST /payment-requests/{paymentRequestRessourceId}/confirmation » et « PUT /payment-requests/{paymentRequestRessourceId} » grâce à son jeton d’accès.
Les appels des méthodes de l’API pourront être enchaînés :
- En exécutant la requête de création du paiement « POST /payment-requests ».
- Puis, en exécutant la requête de récupération du statut du paiement « GET /payment-requests/{paymentRequestRessourceId} en passant en paramètre le « paymentRequestRessourceId » récupéré du résultat de la première requête.
- Puis, en exécutant la requête de confirmation du paiement « POST /payment-requests/{paymentRequestRessourceId}/confirmation » en passant en paramètre le « paymentRequestRessourceId » récupéré du résultat de la première requête.
- Puis, en exécutant la requête d’annulation du paiement « PUT /payment-requests/{payementRequestResourceId} » en passant en paramètre le « paymentRequestRessourceId » et le body modifié récupéré du résultat de la seconde requête.
Les données utilisées pour faire les tests seront issues des personas (voir la rubrique « Comment tester l’API ? » > « Testez nos persona« ), ce qui permettra de choisir des profils spécifiques selon les tests de façon à mieux appréhender les résultats obtenus.
Prérequis
Le TPP doit déclarer son APP en sandbox via notre API Register.
Rappel : en tant que TPP, vous devez être accrédité par l’une des autorités compétentes nationales européennes (ACPR en France) pour le rôle d’initiateur de paiement (« PISP »).
Enchaînement des étapes pour tester l’accès à l’API PISP depuis votre APP
1ère étape : récupérer un jeton d’accès
Cet appel vous permet de récupérer le jeton forgé par la passerelle API de l’ASPSP, et est un prérequis pour chaque accès à l’une des méthodes de l’API d’initiation de paiement.
La description de la fonctionnalité et des champs de la requête est décrite dans la rubrique « Vue d’ensemble » > « Récupérez votre jeton« .
Afin de pouvoir interroger le bon backend dans le parcours client, il est nécessaire que le TPP demande au client au préalable son établissement teneur de compte.
Pour l’accès à l’assemblage sandbox, le point d’entrée dépend du code établissement : www.<cdetab>.sandbox.api.89c3.com
Les seuls établissements bancaires utilisables en assemblage sandbox pour cette API sont les suivants (code établissement <cdetab> utilisé dans les URL) :
| Code établissement | Nom de l’établissement | Nom abrégé |
| 13807 | B.P Grand Ouest | BPGO |
| 17515 | Caisse d’Epargne Ile De France | CEIDF |
Requête :
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/oauth/token
Dans les headers :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
Dans les params :
client_id : PSDFR-ACPR-12345
grant_type : client_credentials
scope : pisp
Remarques sur l’alimentation des champs :
<cdetab> => code établissement des deux banques disponibles dans cet environnement soit :
13807 (Banque Populaire Grand Ouest) ;
17515 (Caisse d’Epargne Ile de France).
client_id :
Si l’enregistrement du TPP a été réalisé au travers du processus de « GoLive » via notre portail BPCE API.
=> numéro d’agrément donné par votre autorité compétente (PSDXX-YYYYYYYY-ZZZZZZZZ)
Ou si l’enregistrement du TPP a été réalisé via l’API registerclient_id retourné dans la réponse au POST /register
=> client_id retourné dans la réponse au POST /register
grant_type => non modifiable = « client_credentials »
Réponse :
{
« access_token » : « firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz »,
« token_type » : « Bearer »,
« expires_in » : « 3600 »,
« scope » : « pisp »
}
Remarques sur l’alimentation des champs :
access_token => tokenCredential à transmettre dans le header authorization des requête de l’API d’initiation de paiement après le Bearer XX.
expires_in => durée de validité du token en secondes.
2ième étape : initier la demande de paiement
Cet appel vous permet d’initier un paiement en demandant au PSU connecté de donner son consentement pour le paiement.
La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Initier un paiement« .
Rappel : la méthode d’authentification supportée par l’établissement bancaire est le mode REDIRECTrenforcé => les cinématiques des enchaînements des écrans d’identification et d’authentification forte décrites ci-après correspondent à ce mode d’authentification.
Requête :
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/v1.6.2/payment-requests
Authorization : Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Headers :
Content-Type : application/json
Signature : keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_<empreinte-sha256>\« , algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\ »
X-Request-ID : MyXrequestId123
Body :
{ « paymentInformationId »: « MyPmtInfld123 », « creationDateTime »: « 2022-09-05T09:25:22.527+02:00 », « numberOfTransactions »: 1, « requestedExecutionDate »: « 2022-09-06T14:10:10.109+01:00 », « debtorAgent »: { « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId » }, « bicFi »: « CCBPFRPP512 », « name »: « Cpy Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue De Gaulle », « 85000 LRSY » ] } }, « initiatingParty »: { « name »: « Pisp Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Reaumur », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 12FR5 », « schemeName »: « COID », « issuer »: « ACPR » } }, « paymentTypeInformation »: { « serviceLevel »: « SEPA », « categoryPurpose »: « DVPM » }, « debtor »: { « name »: « Customer Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Leclerc », « 94512 Charenton-le-Pont » ] } }, « beneficiary »: { « creditor »: { « name »: « Amazon SA », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 avenue Maupassant », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 852126790 », « schemeName »: « BANK », « issuer »: « FR » } }, « creditorAgent »: { « name »: « Creditor Name », « bicFi »: « CCBPFRPP512 », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue de la primaube », « 12512 RODEZ » ] }, « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId! » } }, « creditorAccount »: { « iban »: « FR7613825002000400000541718 » } }, « chargeBearer »: « SLEV », « creditTransferTransaction »: [ { « purpose »: « COMC », « paymentId »: { « instructionId »: « instructionId 1630919339 », « endToEndId »: « endToEndId 1630919339 » }, « instructedAmount »: { « currency »: « EUR », « amount »: « 2.41 » }, « remittanceInformation »: { « unstructured » : [ « remittanceInformation01 » ] } } ], « supplementaryData »: { « acceptedAuthenticationApproach »: [ « REDIRECT » ], « scaHint »: « scaExemption », « successfulReportUrl »: https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK- 12345&code_challenge_method=S256&code_challenge=ABCD } }
Remarques sur l’alimentation des champs :
Authorization : Bearer => access_token récupéré pour le tokenCredential
Les données suivantes devant être unique, sans quoi la requête est rejetée pour cause de doublon (le rejeu n’est pas autorisé) :
– paymentInformationId ;
– instructionId ;
– endToEndId ;
– x-request-id.
debtor/privateId/identification => identifiant d’accès à la banque à distance pour le PSU : lorsqu’il est renseigné et que debtorAccount est renseigné, l’appel à l’écran d’identification du PSU n’est pas effectué.
debtorAccount => IBAN du PSU : lorsqu’il est renseigné, le seul compte sélectionnable pour le PSU est celui qui correspond à cet IBAN, pour peu que le compte soit éligible aux virements PISP.
Les fonctionnalités mises en œuvre peuvent différer entre les Banques Populaires et les Caisses d’Epargne (cf. cas d’usage « Initier un paiement« ).
Réponse :
{
« appliedAuthenticationApproach » : « REDIRECT »,
« _links » : {
« consentApproval » : {
« href » : »https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v2/identificationPisp?paymentRequestRessourceId=00000000a22-156688979900016807956016&nonce=qJammuGI0OGCwznaZ0YO”,
« templated » : true
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 201 OK
Remarques sur l’alimentation des champs :
paymentRequestRessourceId => identifiant à passer à la requête GET /payment-requests pour récupérer le statut de l’initiation de paiement
appliedAuthenticationApproach » = « REDIRECT » => seule valeur autorisée
href => URL de la page de redirection vers les écrans d’identification et d’authentification de l’établissement
nonce => anti rejeu technique
currency => récupérée du body passé en entrée
successfulReportUrl => récupérée du body passé en entrée
unsuccessfulReportUrl => récupérée du body passé en entrée
iban => récupérée du body passé en entrée
creditorName => récupérée du body passé en entrée
X-Request-ID: transmis en entrée
3ième étape : rediriger vers les écrans ASPSP pour que le PSU valide l’opération
Cinématique nominale des enchaînements des écrans d’identification et d’authentification forte
Déroulé de l’enchaînement des écrans d’identification et d’authentification forte :
A partir de l’URI retournée dans « consentApproval« , il est possible de jouer l’enchaînement des écrans.
1) Le PSU est redirigé vers un écran d’identification proposé par son établissement bancaire et dans lequel il saisira son identifiant de banque à distance.
Attention : l’appel à cet écran ne peut être effectué qu’une seule fois
=> le nonce transmis dans l’URL permettant d’accéder à cet écran n’est utilisable qu’une seule fois (il est grillé en suite par l’anti-rejeu)
=> si l’application du TPP ou le PSU ne déroule pas l’ensemble du process en une fois, une nouvelle demande d’initiation de paiement (paymentRequest) sera nécessaire.
L’identifiant de banque à distance du PSU est à saisir (voir rubrique « Comment tester l’API? » > « Tester nos persona » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires :
Remarque : Le bouton « Mémoriser mon identifiant » n’est pas opérationnel. L’activer ne sert à rien.
Pour les Caisses d’Epargne, si le PSU est un professionnel ou une entreprise, il devra saisir son numéro d’usager en plus de son identifiant de banque à distance.
2) Le PSU est redirigé vers un premier écran d’authentification forte proposé par son établissement bancaire pour valider son identité.
Le code SMS pour authentification est à saisir (voir rubrique « Comment tester l’API? » > « Tester nos persona » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires:
En production live : La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du PSU par l’établissement bancaire (SMS OTP, Sécur’Pass, etc.).
Elle dépend aussi de l’équipement du PSU sur lequel tourne l’application du PISP utilisée par le PSU (PC ou mobile/smartphone/tablette).
Note : en environnement de sandbox, le code SMS à saisir est systématiquement : « 12345678 »
3) Le PSU est redirigé vers un écran de sélection de son compte à débiter proposé par son établissement bancaire.
Exemple de restitution pour le persona « Marc » des Banques Populaires qui dispose de 4 comptes (voir rubrique « Comment tester l’API? » > « Tester nos persona » pour les jeux de données de l’établissement) :
NB : Si le PISP fournit l’IBAN du PSU à débiter dans sa requête (champ « debtorAccount »), seul le compte correspondant sera sélectionnable et proposé au PSU : exemple ci-dessous pour le persona Tech’n Co des Banques Populaires.
NB : Si le PSU ne dispose pas de compte, la requête d’initiation de paiement ne va pas aboutir et le PSU va être redirigé vers votre APP. Exemple pour le persona « Thomas » des Banques Populaires.
4) Le PSU sélectionne et valide le compte à débiter.
5) Le PSU est redirigé vers un second écran d’authentification forte proposé par son établissement pour valider son paiement.
Ecrans identiques à l’écran d’authentification forte de l’étape (2) pour valider l’identité du PSU, hormis l’écran de saisi du mot de passe qui n’est pas représenté.
Des exemptions sont possibles pour l’étape d’AF pour valider le paiement => cette possibilité n’est pas disponible.
Le PISP peut renseigner un indicateur lui permettant d’indiquer qu’il considère la demande de paiement comme étant un cas d’exemption d’authentification forte. La décision finale d’appliquer ou non une exemption d’authentification forte reste à l’appréciation de l’ASPSP.
Les cas de dérogation à l’obligation d’authentification forte du PSU si les exigences générales en matière d’authentification sont remplies sont décrits dans l’article 2 des RTS de la DSP2.
6) Le PSU est redirigé vers l’APP du PISP.
Le PISP fournit lors de sa demande d’initiation une ou deux URL de call back :
La première (successfulReportUrl) sera appelée par l’établissement bancaire dans le cas où la demande d’initiation est traitée et si le PSU a donné son consentement pour le paiement. Un paramètre code est ajouté à la successfulReportUrl.
Exemple : https://<votre SuccessfulReportUrl>?code=GbmTn1ZZ76bibgvCRLxD4lNp8wMzkd
Cette information est importante car nécessaire pour obtenir le token d’accès à la méthode confirmation.
La seconde URL (unsuccessfulReportUrl) sera utilisée par l’établissement bancaire en cas de refus du consentement ou si la cinématique de validation de l’initiation de paiement est interrompue à une de ses étapes (exemple : timeout sur l’écran d’identification, sur l’écran de sélection du compte à débiter ou sur les écrans d’authentification forte). Cette seconde URL est facultative : la première URL call back (successfulReportUrl) sera utilisée si la seconde n’est pas renseignée, mais sans ajout de paramètre « code ».
3ème étape alternative : rediriger vers les écrans ASPSP pour que le PSU valide l’opération en cas de parcours fluides
Cinématique nominale des enchaînements des écrans d’identification et d’authentification forte
Par défaut, il est demandé au PSU de s’authentifier fortement à deux reprises pour déclencher une demande de paiement. Il est possible de déclencher deux parcours fluides lorsque la requête contient des informations plus précises sur le compte débiteur :
- Parcours Fluide Bis : le debtorAccount est renseigné dans la demande d’initation de paiement
- Parcours Fluide : le debtorAccount et le privateId (*) sont renseignés dans la demande d’initation de paiement
NB (*) Pour les Caisses d’Epargne, Banque BCP, Crédit Coopératif et BTP Banque et pour les segments de clientèles PRO et ENT : il s’agit du numéro d’abonné séparé du numéro d’usager par un tiret « -« .
| Parcours Fluide Bis | Parcours Fluide |
 |
 |
Le déclenchement du parcours fluide Bis redirige le PSU vers l’écran de saisie de l’identifiant, c’est le même que dans le parcours classique. L’enchainement qui suit est le même peu importe le type de parcours fluide.
1 ) Le PSU est redirigé vers un écran récapitulatif de l’opération, il peut la valider ou l’annuler
Exemple de restitution pour le persona « Marc » des Banques Populaires qui dispose de 4 comptes dont le compte numéro 30019654051, (voir la rubrique « Comment tester l’API ? » > « Testez nos personas » pour les jeux de données de l’établissement) :
2) Le PSU est redirigé vers un premier écran d’authentification forte proposé par son établissement bancaire pour valider son identité.
Le code SMS pour authentification est à saisir ((voir la rubrique « Comment tester l’API ? » > « Testez nos personas« pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires:
La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du PSU par l’établissement bancaire (mot de passe + SMS OTP, secur’pass, etc.).
Elle dépend aussi de l’équipement du PSU sur lequel tourne l’application du PISP utilisée par le PSU (PC ou mobile/smartphone/tablette).
Note : en environnement de sandbox, le code SMS à saisir est systématiquement : « 12345678 »
3 ) Le PSU est ensuite redirigé vers l’APP du PISP, avec la fourniture du paramètre « code »
4ième étape : récupérer le statut d’une initiation de paiement
Cet appel GET /payment-requests/{paymentRequestRessourceId} vous permet de récupérer l’ensemble des données de l’initiation de paiement enrichies du resourceId et des statuts de l’initiation et du paiement qu’elle contient. La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Récupérer le statut« . Les données sont accessibles pendant 35 jours.
Pour l’accès à l’assemblage sandbox, le point d’entrée est identique aux requêtes précédentes :
Requête :
Headers :
Authorization : Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Content-Type : application/json
Signature : keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_<empreinte-sha256>\« , algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\ »
X-Request-ID : MyXrequestId123
Remarques sur l’alimentation des champs :
Authorization : Bearer => access_token récupéré pour le tokenCredential.
x-request-id => doit être le même que pour la requête d’initiation de paiement
Le paymentRequestRessourceId est récupéré en réponse à la requête d’initiation de paiement, lorsque l’initiation de paiement a été traité et que le PSU a donné son consentement pour le paiement.
Réponse :
{ « paymentRequest »: { « resourceId »: « 0000000a22-156688979900016807956016 », « paymentInformationId »: « azertyui 1630919339 », « creationDateTime »: « 2022-09-05T09:25:22.527+02:00 », « numberOfTransactions »: 1, « initiatingParty »: { « name »: « Pisp Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Reaumur », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 12FR5 », « schemeName »: « COID », « issuer »: « ACPR » } }, « paymentTypeInformation »: { « serviceLevel »: « SEPA », « categoryPurpose »: « DVPM » }, « debtor »: { « name »: « Customer Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Leclerc », « 94512 Charenton-le-Pont » ] } }, « debtorAccount »: { « iban »: « FR7613807000243021933556300 » }, « debtorAgent »: { « bicFi »: « CCBPFRPP512 », « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId » }, « name »: « Cpy Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue De Gaulle », « 85000 LRSY » ] } }, « beneficiary »: { « isTrusted »: false, « creditorAgent »: { « bicFi »: « CCBPFRPP512 », « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId! » }, « name »: « Creditor Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue de la primaube », « 12512 RODEZ » ] } }, « creditor »: { « name »: « Amazon SA », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 avenue Maupassant », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 852126790 », « schemeName »: « BANK », « issuer »: « FR » } }, « creditorAccount »: { « iban »: « FR7613825002000400000541718 » } }, « chargeBearer »: « SLEV », « paymentInformationStatus »: « ACCP », « requestedExecutionDate »: « 2022-09-06T14:10:10.109+01:00 », « creditTransferTransaction »: [ { « paymentId »: { « resourceId »: « 0000006537-163091934100113807153727 », « instructionId »: « instructionId 1630919339 », « endToEndId »: « endToEndId 1630919339 » }, « requestedExecutionDate »: « 2022-09-06T15:10:10.109+02:00 », « instructedAmount »: { « currency »: « EUR », « amount »: « 2.41 » }, « purpose »: « COMC », « regulatoryReportingCodes »: [], « remittanceInformation »: { « unstructured »: [ « remittanceInformation01 » ] } } ], « supplementaryData »: { « acceptedAuthenticationApproach »: [ « REDIRECT » ], « appliedAuthenticationApproach »: « REDIRECT », « scaHint »: « scaExemption », « successfulReportUrl »: « https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK-12345&code_challenge_method=S256&code_challenge=ABCD » } }, « _links »: { « request »: { « href »: « /stet/psd2/v1.6.2/payment-requests/00000000a22-156688979900016807956016 », « templated »: false }, « confirmation »: { « href »: « /stet/psd2/v1.6.2/payment-requests/00000000a22-156688979900016807956016/confirmation », « templated »: false } }
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Remarques sur l’alimentation des champs :
resourceId => reprend le paymentRequestRessourceId
paymentInformationStatus => reprend le statut de l’initiation de paiement
transactionStatus => reprend le statut de l’opération resourceId
X-Request-ID: transmis en entrée
5ième étape : confirmer une demande d’initiation de paiement (uniquement en production, PAS en sandbox)
Cet appel POST /payment-requests/{paymentRequestRessourceId}/confirmation vous permet de confirmer une initiation paiement. La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Confirmer une initiation« .
La méthode POST /payment-requests/{paymentRequestRessourceId}/o-confirmation n’est plus implémentée en v1.6.2.
En préalable à la consommation du service confirmation, il est requis d’obtenir un jeton d’accès spécifique via la requête suivante :
Requête :
POST https://www.13807.live.api.89C3.com/stet/psd2/oauth/token
Dans les Headers :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
Dans le body :
grant_type : authorization_code
client_id : PSDFR-ACPR-12345
code : le code récupéré en paramètre de l’appel à la successfulReportUrl en fin d’étape 3
code_verifier : en fonction de vos éléments PKCE
redirect_uri: https://myAPP.fr/Home/OAuth2Callback
Remarques sur l’alimentation des champs :
<cdetab> => code établissement des deux banques disponibles dans cet environnement soit :
13807 (Banque Populaire Grand Ouest) ;
17515 (Caisse d’Epargne Ile de France).
client_id :
Si l’enregistrement du TPP a été réalisé au travers du processus de « GoLive » via notre portail BPCE API :
=> il s’agit du numéro d’agrément donné par votre autorité compétente (PSDXX-YYYYYYYY-ZZZZZZZZ)
OU
si l’enregistrement du TPP a été réalisé via l’API register, client_id retourné dans la réponse au POST /register :
=> il s’agit du client_id retourné dans la réponse au POST /register
redirect_uri : URL de redirection prédéclarée dans votre application consommatrice ET à communiquer à l’ASPSP :
- lors de l’étape GO Assemblage (resp. GO Live en production) si le TPP a été enregistré par la procédure actuelle ;
- via l’API Register si le TPP s’est enregistré par la procédure automatisée.
grant_type => non modifiable = « authorization_code »
Réponse :
{
« access_token » : « secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs »,
« token_type » : « Bearer »,
« expires_in » : « 3600 »,
« refresh_token« : « 1ji8KA9RJ5eXeJV1xKSDj1WDp8wwg3pRgDO2j0WhtbMsWz »,
« scope » : « pisp »,
« state« : « OK-12345 »
}
Remarques sur l’alimentation des champs :
access_token => second token à transmettre dans le header de la prochaine méthode près le Bearer XX.
expires_in => durée de validité du token en secondes.
refresh_token => à mémoriser : permet d’obtenir un nouveau jeton d’accès si le délai de validité du premier jeton est échu (durée de quelques minutes). Le rafraichissement de jeton se fait via le grant-type= refresh_token.
state => L’ASPSP redonne la valeur « state » qui était présente dans la requête initiale de demande d’initiation de paiement (Valeur à la main du TPP).
Une fois le jeton d’accès obtenu, il est possible d’appeler la requête de confirmation de l’initiation de paiement ci-dessous (champ « Authorization »).
Requête:
POST https://www.13807.live.api.89C3.com/stet/psd2/v1.6.2/payment-requests/0000000a22-156688979900016807956016/confirmation
Headers :
Authorization : Bearer secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs
Content-Type : application/json
Signature : keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_<empreinte-sha256>\« , algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\ »
X-Request-ID : MyXrequestId123
Body :
{
}
Authorization : Bearer => second access_token récupéré pour le tokenCredentialRemarques sur l’alimentation des champs :
{paymentRequestRessourceId} : c’est l’identifiant transmis par le service de paiement au moment de l’initiation et qui est utilisé pour le GET
Réponse :
{ « paymentRequest » : {
« resourceId » : « 0000000a22-156688979900016807956016 »,
« paymentInformationId » : « MyPmtInfld123 »,
« creationDateTime » : « 2022-09-05T09:25:22.527+02:00 »,
« numberOfTransactions » : 1,
« debtorAgent » : {
« bicFi » : « CCBPFRPP512 »,
« name » : « Cpy Name »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 rue De Gaulle »,
« 85000 LRSY »
]
}
},
« initiatingParty » : {
« name » : « Pisp Name »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 rue Reaumur »,
« 75512 PARIS »
]
},
« organisationId » : {
« identification » : « 12FR5 »,
« schemeName » : « COID »,
« issuer » : « ACPR »
}
},
« paymentTypeInformation » : {
« serviceLevel » : « SEPA »,
« categoryPurpose » : « DVPM »
},
« debtor » : {
« name » : « Customer Name »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 rue Leclerc »,
« 94512 Charenton-le-Pont »
]
},
« privateId » : {
« identification » : « D0999990I0 »,
« schemeName » : « BANK »,
« issuer » : « BICXYYTT512 »
}
},
« debtorAccount » : {
« iban » : « FR7613807000243021933556300 »
},
« beneficiary » : {
« creditorAgent » : {
« bicFi » : « CCBPFRPP512 »,
« name » : « Creditor Name »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 rue de la primaube »,
« 12512 RODEZ »
]
}
},
« creditor » : {
« name » : « Amazon SA »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 avenue Maupassant »,
« 75512 PARIS »
]
},
« organisationId » : {
« identification » : « 852126790 »,
« schemeName » : « BANK »,
« issuer » : « FR »
}
},
« creditorAccount » : {
« iban » : « FR7613825002000400000541718 »
}
},
« purpose » : « COMC »,
« chargeBearer » : « SLEV »,
« paymentInformationStatus » : « PDNG »,
« statusReasonInformation » : null,
« fundsAvailability » : null,
« booking » : null,
« creditTransferTransaction » : [
{
« paymentId » : {
« resourceId » : « 0000000a22-146329369000016907660677 »,
« instructionId » : « instructionId 1630919339 »,
« endToEndId » : « endToEndId 1630919339 »
},
« requestedExecutionDate » : « 2022-09-06T14:10:10.109+01:00 »,
« instructedAmount » : {
« currency » : « EUR »,
« amount » : « 2.41 »
},
« remittanceInformation »: {
« unstructured »: [
« remittanceInformation01 »
]
},
« transactionStatus » : « PDNG »
}
],
« supplementaryData » : {
« appliedAuthenticationApproach » : « REDIRECT »,
« scaHint » : « scaExemption »,
« successfulReportUrl »: https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK- 12345&code_challenge_method=S256&code_challenge=T3LPv9JWu_HtyEQOkDCo4YYRmZJXTjJ0Ng9jfq_UBBg
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Remarques sur l’alimentation des champs :
paymentRequestRessourceId => identifiant à passer à la requête POST/payment-requests pour confirmer l’initiation de paiement
appliedAuthenticationApproach » = « REDIRECT » => seule valeur autorisée
href => URL de la page de redirection vers les écrans d’identification et d’authentification de l’établissement
nonce => anti rejeu technique
6ième étape : Annuler une demande d’initiation de Paiement
Cet appel vous permet d’annuler une initiation paiement en demandant au PSU connecté de donner son consentement pour l’annulation. La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Annuler une initiation un paiement« .
Rappel : la méthode d’authentification supportée par l’établissement bancaire est le mode REDIRECTsimple => les cinématiques de l’enchaînement de l’écran d’identification et d’authentification forte décrites ci-après correspondent à ce mode d’authentification.
Pour l’accès à l’assemblage sandbox, le point d’entrée est identique : www.<cdetab>.sandbox.api.89c3.com
Requête :
Headers :
Authorization : Bearer secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs
Content-Type : application/json
Signature : keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_<empreinte-sha256>\« , algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\ »
X-Request-ID : MyXrequestId123
Body :
{ « resourceId »: « 0000000a22-156688979900016807956016 », « paymentInformationId »: « MyPmtInfld123 », « creationDateTime »: « 2022-09-05T09:25:22.527+02:00 », « numberOfTransactions »: 1, « initiatingParty »: { « name »: « Pisp Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Reaumur », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 12FR5 », « schemeName »: « COID », « issuer »: « ACPR » } }, « paymentTypeInformation »: { « serviceLevel »: « SEPA », « categoryPurpose »: « DVPM » }, « debtor »: { « name »: « Customer Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Leclerc », « 94512 Charenton-le-Pont » ] } }, « debtorAccount »: { « iban »: « FR7613807000243021933556300 » }, « debtorAgent »: { « bicFi »: « CCBPFRPP512 », « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId » }, « name »: « Cpy Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue De Gaulle », « 85000 LRSY » ] } }, « beneficiary »: { « isTrusted »: false, « creditorAgent »: { « bicFi »: « CCBPFRPP512 », « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId! » }, « name »: « Creditor Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue de la primaube », « 12512 RODEZ » ] } }, « creditor »: { « name »: « Amazon SA », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 avenue Maupassant », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 852126790 », « schemeName »: « BANK », « issuer »: « FR » } }, « creditorAccount »: { « iban »: « FR7613825002000400000541718 » } }, « chargeBearer »: « SLEV », « paymentInformationStatus »: « ACCP », « creditTransferTransaction »: [ { « paymentId »: { « resourceId »: « 0000000a22-156688979900016807956016 », « instructionId »: « instructionId 1630919339 », « endToEndId »: « endToEndId 1630919339 » }, « requestedExecutionDate »: « 2022-09-06T14:10:10.109+01:00 », « instructedAmount »: { « currency »: « EUR », « amount »: « 2.41 » }, « purpose »: « COMC », « regulatoryReportingCodes »: [], « remittanceInformation »: { « unstructured »: [ « remittanceInformation01 » ] }, « transactionStatus »: « RJCT », « statusReasonInformation »: “DS02” } ], « supplementaryData »: { « acceptedAuthenticationApproach »: [ « REDIRECT », « DECOUPLED » ], « appliedAuthenticationApproach »: « REDIRECT », « scaHint »: « scaExemption », « successfulReportUrl »: « https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK-12345&code_challenge_method=S256&code_challenge=T3LPv9JWu_HtyEQOkDCo4YYRmZJXTjJ0Ng9jfq_UBBg » }}
Remarques sur l’alimentation des champs :
Authorization : Bearer => second access_token récupéré
{paymentRequestRessourceId} : c’est l’identifiant transmis par le service de paiement au moment de l’initiation et qui est utilisé pour le GET
Les données du body doivent être identiques à celles récupérées au moment du GET, à part les suivantes au niveau de la transaction à annuler :
– le transactionStatus de l’objet creditTransferTransaction qui doit être passé à « RJCT »
– le statusReasonInformation de l’objet creditTransferTransaction à « DS02 »
– la partie _links doit être supprimée
– l’enveloppe objet du parent « paymentRequest » : {doit être supprimé, ainsi que l’accolade fermante associée en fin de flux.
Réponse :
{ « appliedAuthenticationApproach »: « REDIRECT », « _links »: { « consentApproval »: { « href »: « https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v1.6.2/cancellation?paymentRequestRessourceId=0000000a22-156688979900016807956016&nonce=Ij4VifKlm4QICq12345 », « templated »: true } }}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Remarques sur l’alimentation des champs :
paymentRequestRessourceId => identifiant à passer à la requête GET /payment-requests pour récupérer le statut de l’initiation de paiement
appliedAuthenticationApproach » = « REDIRECT » => seule valeur autorisée
href => URL de la page de redirection vers les écrans d’identification et d’authentification de l’établissement
nonce => anti rejeu technique
currency => récupérée du body passé en entrée
successfulReportUrl => récupérée du body passé en entrée
unsuccessfulReportUrl => récupérée du body passé en entrée
creditorAccount => récupérée du body passé en entrée
creditorName => récupérée du body passé en entrée
amount => récupérée du body passé en entrée
successfulReportUrl => récupérée du body passé en entrée
debtorAccount => récupérée du body passé en entrée
debtorName => récupérée du body passé en entrée
privateId => récupérée du body passé en entrée
requestedExecutionDate=> récupérée du body passé en entrée
method => UFVU est égal à PUT en base64 + URL
X-Request-ID: transmis en entrée
7ième étape : rediriger vers les écrans ASPSP pour que le client valide l’annulation d’une initiation de paiement
Cinématique nominale des enchaînements des écrans d’identification et d’authentification forte
Déroulé de l’enchaînement des écrans d’identification et d’authentification forte :
A partir de l’URI retournée dans consentApproval il est possible de jouer l’enchaînement des écrans :
1) Le PSU est redirigé vers un écran d’identification proposé par son établissement bancaire et dans lequel il saisira son identifiant de banque à distance.
Attention : l’appel à cet écran ne peut être effectué qu’une seule fois
=> le nonce transmis dans l’URL permettant d’accéder à cet écran n’est utilisable qu’une seule fois (il est grillé en suite par l’anti-rejeu)
=> une nouvelle demande d’annulation de virement DSP2 (via PUT PaymentRequest ) est nécessaire pour récupérer un nouveau jeton nonce si nécessaire.
L’identifiant de banque à distance du PSU est à saisir (voir la rubrique « Comment tester l’API ? » > « Testez nos personas » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires :
Pour les Caisses d’Epargne, si le PSU est un professionnel ou une entreprise, il devra saisir son numéro d’usager en plus de son identifiant de banque à distance :
2) Le PSU est redirigé vers un écran d’authentification forte proposé par son établissement bancaire pour valider son identité.
Le code SMS pour authentification est à saisir (voir la rubrique « Comment tester l’API ? » > « Testez nos personas » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires:
La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du PSU par l’établissement bancaire (SMS OTP, secur’pass, etc.).
Elle dépend aussi de l’équipement du PSU sur lequel tourne l’APP du PISP utilisée par le PSU (PC ou mobile/smartphone/tablette).
Remarque : en environnement sandbox, le code SMS est systématiquement « 12345678 ».
3) Le PSU est redirigé vers un écran récapitulatif de l’opération en cours d’annulation proposé par son établissement bancaire.
Exemple de restitution pour le persona « Marc » des Banques Populaires veut annuler sa transaction de 2,12 euros émise depuis son Compte Perso. Il peut annuler ou valider son opération d’annulation.
4) Le PSU valide l’annulation du virement.
5) Le PSU est redirigé vers un écran de confirmation de l’opération proposé par son établissement bancaire.
NB : lorsque le PSU ne confirme pas l’annulation de paiement (ou en cas de timeout sur la page récapitulative de l’opération par exemple) le PSU est redirigé vers la page suivante,
6) Le PSU est redirigé vers l’application du TPP PISP.
Le PISP fournit lors de sa demande d’annulation une ou deux URL de call back :
La première (successfulReportUrl) sera appelée par l’établissement bancaire dans le cas où la demande d’annulation est traitée et si le PSU a donné son consentement pour cette annulation d’opération.
La seconde URL (unsuccessfulReportUrl) sera utilisée par l’établissement bancaire en cas de refus du consentement ou si la cinématique de validation de l’annulation de paiement est interrompue à une de ses étapes (exemple : timeout sur l’écran d’identification, sur l’écran récapitulatif de l’opération ou sur les écrans d’authentification forte). Cette seconde URL est facultative : la première URL call back (successfulReportUrl) sera utilisée si la seconde n’est pas renseignée.
NB : la confirmation d’une annulation d’une demande de paiement ne sera pas implémentée : la confirmation sera implicitement portée par l’acception par le PSU de la demande d’annulation elle-même.
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.6.2.0, afin de répondre aux exigences règlementaires de la DSP2. Elle tient compte des limitations fonctionnelles à l’ASPSP telles que 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 :
Versionning de l’API
| Notre version API | Version norme STET |
| v1.6.2 | v1.6.2.0 |
Evolutions importantes apportées depuis la première version livrée
| Cas d’usage / Méthode(s) | Date d’effet | Description de l’évolution |
| Toutes | 16 novembre 2022 | Reprise de toutes les évolutions des versions précédentes des API v1 et v1.4.2 |
| Toutes | 16 novembre 2022 | Rajout des spécificités de la version API v1.6.2 |
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.
| Version de l’API | Fonctionnalités | Date de déploiement
BPCE API Dev Portal & Sandbox |
Date de déploiement
BPCE Live API Gateway |
Date de décommissionnement |
| v1.6.2 | API version 1 :
API version V1.4.2 = API version version 1 plus :
API version V1.6.2 = API version V1.4.2 plus :
|
16 novembre 2022 | 28 février 2023 | non encore annoncée |
| v1.6.2 | Fonctionalités ci-dessus plus :
|
juin 2023 | juin 2023 | non encore annoncée |
Limitations
Limitations fonctionnelles
Limitations de cette API DSP2
- S’applique à toutes les Caisses d’Epargne sauf cas particulier éventuellement décrit dans cette section
- Ne s’applique qu’aux comptes de paiements en euros actifs accessibles en ligne (cf. texte de la Directive PSD2), et aux virements externes entre comptes
- N’utilise que le mode d’authentification REDIRECT renforcé avec confirmation (appel de la méthode confirmation pour que le TPP confirme le paiement après Authentification Forte du PSU demandée et gérée via la banque : l’ASPSP transmet un code d’autorisation OAUTH2 au TPP qui doit le renvoyer à l’ASPSP pour confirmer le 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)
- Ne traite que les demandes d’initiation de paiement en euro (PAS d’initiation de virement en devise)
- SCT Core unitaire de type immédiat ou différé ou permanent pour les segments de clients PART/EI/PRO/ENT
- SCT Core multiple de type immédiat (PAS de multi-dates) pour les segments de clients PRO/ENT d’un compte débiteur vers N créditeurs résultant en N opérations avec différents montants possibles, et que pour les types de categoryPurpose = « CASH » et « SALA »
- SCT INST pour les segments de clients PART/EI/PRO/ENT (SAUF pour les CE Ile de France et CE Auvergne Limousin : que pour les PART/EI)
- Le BIC Creditor n’est pas nécessaire SAUF pour les opérations PIS hors zone SEPA (toujours en euro)
- Les méthodes suivantes sont disponibles :
- POST /payment-requests et POST /payment-requests/{paymentRequestRessourceId}/confirmation pour initier une demande
- GET /payment-requests/{paymentRequestRessourceId} pour récupérer le statut d’une initiation de paiement
- PUT /payment-requests/{paymentRequestRessourceId} n’est supportée que pour annuler un virement unitaire (virement SCT différé ou permanent, non applicable pour un virement multiple)
NB : Les méthodes suivantes ne sont PAS supportées : POST /payment-requests/{paymentRequestRessourceId}/o-confirmation et GET /payment-requests/{paymentRequestRessourceId}/transactions
- L’annulation d’une demande de virement unitaire (hors SCT Inst et virement multiple) via API PIS peut être effectuée :
- par le PSU via son accès direct avant une heure limite
- par le TPP via API avant une heure limite
- Les demandes PIS de type « CASH » et « SALA » seront rejetés si le PSU n’utilise pas un moyen d’authentification forte ayant un niveau suffisemment sécuritaire (Secur’Pass ou le certificat sur clé physique pour les PRO & ENT), et si l’IBAN bénéficiaire n’est pas enregistré au préalable sur son accès direct
- Différentes demandes PIS ayant les mêmes caractéristiques qu’une préalablement executée (même jour, même IBAN debiteur et créditeur, même montant, etc…) sont rejetées (fonctionnement identique à la banque en ligne)
- Si aucune action de l’utilisateur n’est effectuée au bout de 30 mns (04 mns sur les écrans de redirection), c’est considéré comme une déconnexion sans redirection en retour vers le TPP
- Si le PSU a plusieurs IBAN liés à un même abonnement, le nombre maximum de comptes de paiements éligibles DSP2 affichés lors du parcours classique est limité à 10 lignes
- La longueur du champs creditor.name est limitée à 32 caractères
Limitations liées aux types de comptes accessibles
- Les comptes accessibles via l’API PISP sont ceux disponibles sur la banque à distance éligibles DPS2 pour initier un virement SEPA vers un bénéficiaire externe
- Il est à noter qu’en adéquation avec la réglementation, l’ASPSP peut appliquer des processus métiers (lutte anti-fraude, etc…) qui peuvent amener à rejeter l’exécution d’une initiation de paiement
Limitations liées aux segments de clientèle
Sont couverts par l’API les segments clients suivants :
- Client « particulier » (y compris compte joint et mineur rattaché) ayant un abonnement à la banque en ligne « DEI PART » ou « DEI PRO » et un compte commençant par 04
NB 1 : le particulier (PART) est une personne physique catégorisée comme « majeur capable ». Le PART peut aussi avoir des activités dans le cadre d’une entreprise individuelle (EI) = une entreprise dirigée par une seule personne, et qui n’a pas le statut de « persone morale », bien qu’elle soit inscrite au répertoire des métiers ou au Registre du Commerce et des Sociétés (RCS, exemples : artisan ou profession libérale). Dans ce cas, l’EI est considéré comme un PART
NB 2 : est non compris à ce jour le tuteur de personne protégée/sous tutelle ou curatelle utilisant la solution Web Protexion
- Client « gros professionnel », « entreprise » et « association » ayant un abonnement à la banque en ligne « CE Net Compte » et un compte commençant par 08 autorisant les virements unitaires
NB 3 : les catégories « entreprise » (ENT) et « association » (ASSOC) couvrent les personnes morales
Limitations liées aux moyens d’authentification forte
Il est de la responsabilité de l’ASPSP d’équiper ses clients avec un ou des moyens d’authentification forte :
- PART : Accès aux comptes PART et Opération sensible / Dynamic linking (DL) : (Sécur’Pass) ou (lecteur CAP) ou (Mot de Passe + OTP SMS)
- PRO/ENT : Accès aux comptes PART et Opération sensible / Dynamic linking (DL) : (certificat matériel) ou (Sécur’Pass) ou (lecteur CAP) ou (Mot de Passe + OTP SMS)
NB 4 : il n’y a pas d’exemption de la seconde authentification forte AF/SCA dynamic linking (donnée scaHint ignorée)
NB 5 : il y aura un rejet des virements avec categoryPurpose = « CASH » ou « SALA » lorsque l’AF/SCA DL ne se fait pas avec le moyen principal et que l’IBAN bénéficiaire n’est pas enregistré par le PSU sur sa banque en ligne
NB 6 : le certificat matériel n’est pas proposé aux client sur mobile/smartphone
Accès aux données de production
Conformément à la réglementation, les modes de test d’assemblage (sandbox) n’utilisent que des données fictives qui sont décrites dans le cas d’usage « 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).
Le code établissement (voir la liste des établissements bancaires accessibles ci-dessous) vous permettra d’adresser le bon référentiel client via le « endpoint » www.<codetab>.live.api.89c3.com (ou www.<codetab>.live.api.caisse-epargne.fraligné sur le nom de domaine de l’accès directwww.caisse-epargne.fr).
Une fois choisi, ce point d’accès doit être conservé pour toutes les requêtes sous-jacentes.
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).
| Code établissement | Nom de l’ASPSP | Nom abrégé | Disponible en
Assemblage |
Disponible en
Production |
| 11315 | Caisse d’Epargne Provence Alpes Corse | CEPAC | – | Oui |
| 11425 | Caisse d’Epargne Normandie | CEN | – | Oui |
| 12135 | Caisse d’Epargne Bourgogne Franche-Comté | CEBFC | – | Oui |
| 14445 | Caisse d’Epargne Bretagne-Pays De Loire | CEBPL | – | Oui |
| 13135 | Caisse d’Epargne Midi-Pyrénées | CEMP | – | Oui |
| 13335 | Caisse d’Epargne Aquitaine Poitou-Charentes | CEAPC | – | Oui |
| 13485 | Caisse d’Epargne Languedoc-Roussillon | CELR | – | Oui |
| 13825 | Caisse d’Epargne Rhône Alpes | CERA | – | Oui |
| 14265 | Caisse d’Epargne Loire Drôme Ardèche | CELDA | – | Oui |
| 14505 | Caisse d’Epargne Loire-Centre | CELC | – | Oui |
| 17515 | Caisse d’Epargne Ile De France | CEIDF | Oui | Oui |
| 18315 | Caisse d’Epargne Côte d’Azur | CECAZ | – | Oui |
| 18715 | Caisse d’Epargne Auvergne et Limousin | CEPAL | – | Oui |
| 15135 | Caisse d’Epargne Grand Est Europe | CEGEE | – | Oui |
| 16275 | Caisse d’Epargne Hauts de France | CEHDF | – | Oui |
