Initier un paiement
Un de nos clients effectue une transaction sur un site d’e-commerce ou souhaite effectuer un virement ou un transfert unitaire ou multiple.
Via cette API « Initiation de paiement » mise à disposition par notre banque, vous pouvez soumettre en temps réel une demande d’initiation du paiement.
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 minute 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 vos services afin de réaliser un virement ou un transfert unitaire ou multiple, 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 vous précise la banque dans laquelle il est domicilié à travers vos interfaces.
2- Lors du premier échange avec les infrastructures du teneur de compte, vous allez faire une demande de jeton d’autorisation. Le principe de base est, qu’en tant que TPP PISP, vous devez obtenir ce jeton AVANT de consommer l’API. Ce jeton est généré par le teneur de compte (ASPSP) APRES avoir vous avoir identifié.
En tant que teneur de compte, nous allons :
- Vérifier vos certificats et agréments.
Pour cette API, il n’est pas nécessaire que nous identifiions et authentifions fortement le client afin de récupérer son consentement et de générer le jeton d’accès.
3- Si nous avons pu vérifier votre identité et vos agréments, vous pourrez 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, vous pourrez 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 » > « Récupérer le statut d’une initiation de paiement« ) ;
- De modifier une initiation de paiement (voir la rubrique « Cas d’usage » > « Annuler une initiation de paiement« )
- De confirmer une initiation de paiement (voir la rubrique « Cas d’usage » > « Confirmer une initiation de paiement – méthode confirmation« ).
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 (ACPR) pour le rôle d’initiateur de paiement (« PISP »).
Pour accéder aux services de l’API d’initiation de paiement, vous devez récupérer un jeton d’accès OAUTH2 délivré par l’établissement bancaire du PSU en l’interrogeant avec vos credentials.
A ce titre, vous devez vous authentifier mutuellement avec le teneur de compte (ASPSP) par échange de certificats eIDAS QWAC.
Vous présenterez ensuite votre 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 : le client PSU achète des biens ou des services sur un site e-commerce (cf. haut du schéma ci-après).
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 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 (cf. bas du schéma ci-après).
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 / section 3.4.5.3 page 50
Vous transmettez 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 multipledans 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 ou multipleSCT 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, vous annulez 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.
Assemblage sandbox
Introduction – précisions sur les fonctionnalités de la sandbox
La sandbox BPCEC API peut être utilisée de 2 manières :
- Via le Try-it du portail BPCE-API (voir la rubrique « Comment tester l’API ? » > « Console Try-it« )
- Directement via votre application en appelant l’API « Initiation de paiement » de la plateforme BPCE API (assemblage sandbox)
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 « Initiation de paiement » (voir les cas d’usage « Initier un paiement« , « Récupérer le statut d’une initiation de paiement« , « Confirmer une initiation de paiement » et « Annuler une initiation de paiement »).
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 :
- 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).
Votre application 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 votre application pourra consommer les méthodes « POST /payment-requests« , « GET /payment-requests/{payementRequestResourceId}« , « POST /payment-requests/{payementRequestResourceId}/o-confirmation » et « PUT /payment-requests/{payementRequestResourceId} » 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/{paymentRequestResourceId} en passant en paramètre le « paymentRequestResourceId » 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/{paymentRequestResourceId}/o-confirmation » en passant en paramètre le « paymentRequestResourceId » 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 « paymentRequestResourceId » 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
Vous devez déclarer votre APP sur le portail BPCE API (cf. menu « Mes applications« ) et nous transmettre les clés publiques de vos certificats QWAC et QSEALC de test afin que nous puissions :
- Déclarer votre APP comme application consommatrice de l’API ;
- Intégrer vos clés publiques QWAC et QSEALC dans nos infrastructures ;
- Récupérer et contrôler votre organizationId et votre rôle « PISP » dans notre registre des TPP.
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 le serveur d’authentification de l’établissement et qui 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 vous prévoyiez d’interroger le client au préalable sur son établissement de rattachement.
Pour l’accès à l’assemblage sandbox, le point d’entrée dépend du code établissement : www.<cdetab>.sandbox.api.89c3.com
Les seuls établissements bancaires utilisables en assemblage sandbox pour cette API sont les suivants (code établissement <cdetab> utilisé dans les URL) :
| Code établissement | Nom de l’établissement | Nom abrégé |
| 13807 | B.P Grand Ouest | BPGO |
| 13807 | CMM Grand Ouest | CMMGO |
| 17515 | Caisse d’Epargne Ile De France | CEIDF |
| 12579 | Banque BCP | BBCP |
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.
2ème étape : Initier un 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.
Pour l’accès à l’assemblage sandbox, le point d’entrée est identique : www.<cdetab>.sandbox.api.89c3.com
Requête :
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/v1.4.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 »: « 2021-09-05T09:25:22.527+02:00 », « numberOfTransactions »: 1, « requestedExecutionDate »: « 2021-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?paymentRequestResourceId=00000000a22-156688979900016807956016&nonce=qJammuGI0OGCwznaZ0YO”,
« templated » : true
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 201 OK
Remarques sur l’alimentation des champs :
paymentRequestResourceId => 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
3ème étape : La redirection vers les écrans pour que le PSU valide le 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)
=> 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, 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 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 o-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 : La redirection vers les écrans pour que le PSU valide le paiement 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
| Parcours Fluide Bis | Parcours Fluide |
 |
 |
(*) 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 « -« .
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 »
4ème étape : Récupérer le statut d’une initiation de paiement
Cet appel GET /payment-requests/{paymentRequestResourceId} 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 d’une initiation de paiement« . 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 paymentRequestResourceId 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 »: « 2021-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 »: « 2021-09-06T14:10:10.109+01:00 », « creditTransferTransaction »: [ { « paymentId »: { « resourceId »: « 0000006537-163091934100113807153727 », « instructionId »: « instructionId 1630919339 », « endToEndId »: « endToEndId 1630919339 » }, « requestedExecutionDate »: « 2021-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.4.2/payment-requests/00000000a22-156688979900016807956016 », « templated »: false }, « confirmation »: { « href »: « /stet/psd2/v1.4.2/payment-requests/00000000a22-156688979900016807956016/o-confirmation », « templated »: false } }
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Remarques sur l’alimentation des champs :
resourceId => reprend le paymentRequestResourceId
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
5ème étape : Confirmer une initiation de paiement (uniquement en production, PAS en sandbox)
Cet appel POST /payment-requests/{paymentRequestResourceId}/o-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 un paiement« .
La méthode POST /payment-requests/{paymentRequestResourceId}/confirmation n’est pas implémentée.
En préalable à la consommation du service o-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:
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 :
{
}
Remarques sur l’alimentation des champs :
Authorization : Bearer => second access_token récupéré pour le tokenCredential
{paymentRequestResourceId} : 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 » : « 2021-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,
« requestedExecutionDate » : « 2021-09-06T14:10:10.109+01:00 »,
« creditTransferTransaction » : [
{
« paymentId » : {
« resourceId » : « 0000000a22-146329369000016907660677 »,
« instructionId » : « instructionId 1630919339 »,
« endToEndId » : « endToEndId 1630919339 »
},
« 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 :
paymentRequestResourceId => 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
6ème étape : Annuler une 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 »: « 2021-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 »: « 22021-09-06T14:10:10.109+01:00 », « creditTransferTransaction »: [ { « paymentId »: { « resourceId »: « 0000000a22-156688979900016807956016 », « instructionId »: « instructionId 1630919339 », « endToEndId »: « endToEndId 1630919339 » }, « requestedExecutionDate »: « 2021-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é
{paymentRequestResourceId} : 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.4.2/cancellation?paymentRequestResourceId=0000000a22-156688979900016807956016&nonce=Ij4VifKlm4QICq12345 », « templated »: true } }}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Remarques sur l’alimentation des champs :
paymentRequestResourceId => 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
7ème étape : La redirection vers les écrans 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 :
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 é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 propres à la Banque de Savoie 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.
Vous pouvez aussi consulter l’assistant virtuel au sujet des spécifications STET.
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 utilisateur est accessible via le formulaire sur ce portail 89C3 API, ou via https://www.api.89c3.com/fr/nous-contacter. Les réponses se font pendant les heures de travail ouvrées.
Afin d’interroger une API, la version de l’API inclut le numéro de version dans l’URI appelée, soit par exemple : /stet/psd2/v1.6.2/payment-requests.
Le cas d’usage « Roadmap » donne la table de correspondance entre la version de l’API et la version de la spécification utilisée, soit par exemple la v1 de l’API correspond à la version V1.4.0.47 des spécifications STET, la v1.4.2 correspond à la version v1.4.2.17 des spécifications STET et la v1.6.2 correspond à la version v1.4.6.0 des spécifications STET.
Le principe de la durée de support est schématisée ci-dessous en prenant en compte l’article 30 (4) des RTS :
Versionning de l’API
| Nos versions API | Version norme STET |
| v1 | v1.4.0.47 |
| v1.4.2 | v1.4.2.17 |
| v1.6.2 | v1.6.2.0 |
Vous pouvez consulter l’assistant virtuel au sujet des textes de la norme STET.
Evolutions importantes apportées depuis la première version livrée
| Cas d’usage / Méthode(s) | Date d’effet | Description de l’évolution |
| POST /payment-requests GET /payment-requests/{paymentRequestResourceId} | 17 mai 2019 | Documentation portail :
|
| Toutes | 31 juillet 2019 | Documentation portail :
|
| Roadmap | 18 septembre 2019 | Documentation portail :
|
| Eligibilité | 1er octobre 2019 | Documentation portail :
|
| Initier un paiement | 19 novembre 2019 | Documentation portail:
|
| Comment utiliser le fallback | 21 novembre 2019 | Documentation portail :
|
| Récupérer le statut d’une initiation de paiement | 9 décembre 2019 | Documentation portail :
|
| Tester nos persona | 23 décembre 2019 | Documentation portail :
|
| Initier un paiement | 24 décembre 2019 | Activation de la prise en compte de l’IBAN transmis dans le champ debtorAccount => IBAN du PSU : lorsqu’il est renseigné, le seul compte sélectionnable pour le PSU est celui qui correspond à cet IBAN. |
| Historique des versions / roadmap | 30 décembre 2019 | Documentation portail :
|
| Limitations / Historique des versions / roadmap | 25 février 2020 | Activation de l’API pour les autres BP que BPGO.
Modification du versionning de l’API. |
| Annuler une initiation de paiement / sandbox / limitations | 10 septembre 2020 | Activation de la méthode d’annulation d’une initiation de paiement. |
| POST /payment-requests | 2 décembre 2020 | Documentation portail :
|
| Initier un paiement / Récupérer le statut d’une initiation de paiement / Sandbox / Roadmap | 22 décembre 2020 | Depuis le 7 décembre :
|
| Toutes | 4 janvier 2021 | Documentation portail :
|
| Toutes | 19 juillet 2021 | Documentation portail :
|
| Initier un paiement | 22 juillet 2021 | Documentation portail :
|
| Sandbox / Try-IT | 23 septembre 2021 | Documentation portail :
|
| Initier un paiement | 27 septembre 2021 | Documentation portail :
|
| Toutes | 22 mars 2022 | Documentation portail :
|
| Initier un paiement / limitations | 20 avril 2022 | Documentation portail :
|
| Toutes | 26 septembre 2022 | Documentation portail :
|
| Confirmation | 21 mars 2023 | Documentation portail :
|
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 | Version de la norme STET | Fonctionnalités | Sandbox
Date de déploiement BPCE API Dev Portal & Sandbox |
Live
Date de déploiement BPCE Live API Gate way |
Date de décommissionnement |
| v1 | v1.4.0.47 |
|
14 mars 2019 (1ère version)
7 octobre 2019 (mode REDIRECT) |
7 octobre 2019 | Avril 2023
(à confirmer) |
| v1 | v1.4.0.47 |
|
24 août 2020 | 24 août 2020 | Avril 2023
(à confirmer) |
| v1 | v1.4.0.47 |
|
7 décembre 2020 | 7 décembre 2020 | Avril 2023
(à confirmer) |
| v1.4.2 | v1.4.2.17 |
|
30 mai 2021 | 30 mai 2021 | |
| v1.4.2 | v1.4.2.17 |
|
30 juin 2021 | 30 juin 2021 | |
| v1.4.2 | v1.4.2.17 |
|
30 mars 2022 | 30 mars 2022 | |
| v1.6.2 | v.1.6.2.0 |
|
20 octobre 2022 | 8 février 2023 | |
| v1.6.2 | v.1.6.2.0 |
|
22 février 2023 | 22 février 2023 |
Limitations
Limitations fonctionnelles
Limitations de cette API DSP2 en version 1.6.2
- S’applique à la Banque de Savoie
- Ne s’applique qu’aux comptes de paiements en euros actifs et accessibles en ligne (cf. texte de la Directive PSD2) ;
- N’utilise que le mode d’authentification REDIRECTrenforcé (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’authorisation 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 €uro
- Donc pas d’initiation de virement en devise
- Des virements unitaires SEPA SCT de type immédiat, permanent ou différé, ou des SEPA Instant Payment (SCTInst)
- Des virements multiples SEPA SCT de type immédiat ou différé.
- Le champ chargeBearer est obligatoire pour la méthode POST /payment-requests et doit valoir SLEV, pour les paiements internationaux (i.e. en devise hors EUR) => les virements internationaux en devise ne sont pas disponibles
- Le champ categoryPurpose est obligatoire pour la méthode POST /payment-requests :
- CASH, SALA et DVPM sont possibles pour un virement unitaire ;
- CASH et SALA sont possibles pour un virement multiple.
- Les méthodes suivantes sont disponibles :
- POST /payment-requests et POST /payment-requests/{paymentRequestResourceId}/confirmation pour initier un paiement pour un virement unitaire ou un virement multiple
- GET /payment-requests/{paymentRequestResourceId} pour récupérer le statut d’une initiation de paiement pour un virement unitaire ou un virement multiple
- La méthode PUT /payment-requests/{paymentRequestResourceId} n’est supportée que pour annuler une initiation de paiement pour un virement unitaire (virement SCT différé ou permanent) ou un virement multiple (SCT différé).
- La méthode POST /payment-requests/{paymentRequestResourceId}/o-confirmation n’est plus supportée en v1.6.2
- La méthode GET /payment-requests/{paymentRequestResourceId}/transactions n’est pas supportée.
- Identifiant de banque à distance du client de la banque pris en compte (via la donnée debtor/privateId/identification ) pour déclencher un parcours PISP fluide (une seule authentification forte) si le debtorAccountest aussi renseigné dans la requête
- Un virement initié via l’API d’initiation de paiement, ne peut être annulé par le PSU via son accès direct sur la banque en ligne.
- Si aucune action de l’utilisateur n’est effectuée au bout de 30 mns (ou 04 mns sur les écrans de redirection), c’est considéré comme une déconnexion sans redirection en retour vers le TPP
Limitations liées aux segments de clientèle
- Le particulier (PART) est une personne physique catégorisée comme « majeur capable »
- Les catégories « professionnel » (PRO) et « entreprise » (ENT) couvrent les personnes morales
Limitations liées aux types de comptes accessibles
- Les comptes accessibles via l’API PISP à débiter sont ceux disponibles sur la banque à distance 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 moyens d’authentification forte
- Client particulier (PART) : équipement avec Mot de passe + SMS OTP et/ou Sécur’pass (déclenché en priorité le cas échéant)
- Client professionnel (PRO) et entreprise (ENT) : équipement Certificat et/ou Sécur’Pass et/ou lecteur CAP et/ou Mot de passe + OTP SMS
NB : Il n’y a pas d’exemption d’authentification forte (donnée scaHint ignorée)
Accès aux données de production
Conformément à la réglementation, les modes de test Try-it et Assemblage n’utilisent que des données fictives. Ces données de tests sont décrites dans les cas d’usage « Comment Tester l’API ?« .
Pour accéder aux données de production, il est nécessaire d’utiliser notre API d’auto-enrôlement « API Register » (voir la fiche produit dédiée).
La plage hebdomadaire du dimanche matin de 2h à 6h est utilisée si besoin pour la maintenance des backends / des gateways et peut engendrer des requêtes KO le temps que les serveurs concernés aient tous été mis à jour pour l’établissement concerné.
Comme en mode test, le code établissement (voir la liste des établissements bancaires accessibles ci-dessous) vous permettra d’adresser le bon référentiel client via le « endpoint » www.10548.live.api.89c3.com ou www.10548.live.api.banque-de-savoie.fraligné sur le nom de domaine de l’accès directwww.banque-de-savoie.fr
Une fois choisi, ce point d’accès doit être conservé pour toutes les requêtes sous-jacentes.
| Code établissement | Nom de l’établissement | Nom abrégé | Disponible en Try-it et Assemblage | Disponible en Production |
| 10548 | Banque de SAVoie | BQSAV | Oui |
