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

Prérequis

En tant que TPP, vous devez être accrédité par l’autorité de contrôle prudentiel et de résolution (ACPR en France) 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 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.4.2 / Part 1 / paragraphe 3.4.5.4

Image

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}/o-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 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}/o-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 paiement qu’elle contient.

Les données sont accessibles pendant 35 jours.

Annuler une initiation de paiement

Pour un virement SCT différé qui n’a pas encore été exécuté ou pour un virement 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 du virement.

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}/o-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.

Publications réglementaires

Récupérer un jeton

Développement pas à pas

1- Le TPP envoie directement une requête vers l’infrastructure informatique d’autorisation de la banque teneur de compte.

Pour l’accès en production (Live), le point d’entrée pour récupérer le jeton d’accès dépend de l’établissement teneur de compte avec le format

• htpps://www.<cdetab>.live.api.89c3.com/stet/psd2/oauth/token

ou

• htpps://www.<cdetab>.live.api.<banque>/stet/psd2/oauth/token aligné sur le nom de domaine de l’accès direct de la <banque>

NB : la liste de nos établissements et les valeurs possibles des <cdetab> et <banque> associés sont précisées dans la rubrique « Limitations » .

Afin de pouvoir interroger le bon backend dans le parcours client, il est donc nécessaire que vous prévoyez de demander au préalable au client son établissement teneur de compte.

NB : Le PSU peut domicilier ses comptes dans plusieurs banques du Groupe BPCE. Dans ce cas, il vous faudra un jeton différent pour accéder à chacun des établissements teneurs de comptes (ASPSP).

Le détail des paramètres de la requête se trouvent ci-après : POST /psd2/oauth/token?client_id={clientId}&scope={scope}[&grant-type=client_credentials]

2- L’établissement teneur de compte (ASPSP) va effectuer des vérifications liées au profil du TPP (rôle, validité des certificats et de votre rôle, non révocation de votre profil, etc.)

3- Si ces vérifications effectuées sont concluantes, la banque va répondre au TPP via un code HTTP 200 (OK) avec les données suivantes :

Le jeton d’accès doit être utilisé dans toutes les requêtes au niveau du header « Authorization » préfixé par le type de jeton « Bearer ».

Si le jeton a expiré, la requête sera rejetée avec un code HTTP 403 et des données indiquant « Token invalide ». 

Cette requête pourra être renvoyée une fois qu’un nouveau jeton d’accès de type Client Credential a été demandé et obtenu.

Initier un paiement

Cas d’usage

Envoyer une demande d’initiation de paiement unique en €.

Contexte

Cet appel permet d’envoyer à la banque (ASPSP) d’un client une demande d’initiation de paiement venant débiter son compte. 

S’il s’agit d’une initiation de paiement initiée par un e-commerçant (pas par le client final), le paiement va créditer celui de l’usager du service de paiement (PSU) pour lequel le Prestataire de service de paiement (PISP) a été mandaté, à savoir le e-commerçant.

Seule l’initiation de paiement unique en euros est acceptée dans nos traitements.

A la soumission de la requête, et si toutes les données sont correctement formatées, une réponse (HTTP 201) vous sera retournée.

Cette réponse contiendra le resourceId de l’initiation de paiement, ainsi que le mode d’authentification SCA Redirect (seul mode disponible), l’URL de consentement en fonction de la banque du payeur (urlconsent_approval_URL) et le non rejeu.

Prérequis

Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité pour le rôle TPP « PISP » (voir la rubrique « Eligibilité« ), et d’avoir récupéré le jeton d’accès OAuth2 (voir la rubrique « Cas d'usage » > « Récupérer un jeton » ).

Requête POST

Le point d’entrée dépendra du code établissement.

Vous devez insérer la même valeur des paramètres <cdetab> et <banque> que celle utilisée pour le jeton d’accès.

Pour rappel, la liste de nos établissements et les valeurs possibles des <cdetab> et <banque> sont précisées dans la rubrique « Limitations » .

Voici un extrait de cette liste :

Comme en mode test, le bon référentiel client est adressable via un « endpoint » au format www.<cdetab>.live.api.89c3.com ou www.<cdetab>.live.api.<banque>.fr

Pour exemple, nous avons donc comme URL de production :

• POST https://www.13807.live.api.89c3.com/stet/psd2/v1.4.2/payment-requests ou https://www.13807.live.api.banquepopulaire.fr/stet/psd2/v1.4.2/payment-requests pour initier un paiement pour un client de la BPGO en production

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

La structure du body et les champs obligatoires sont décrits dans la norme STET.

Les informations suivantes doivent être valorisées dans la requête comme suit :

• La donnée serviceLevel doit être renseignée à SEPA.
   
• La donnée currency doit être renseignée à EUR => les virements internationaux en devise ne sont pas disponibles.
   
• La donnée requestedExecutionDate doit être égale ou supérieure à la date du jour.
   
• La donnée numberOfTransactions doit être valorisée à « 1 » (puisque seules les initiations de paiement de virements unitaires sont supportées).
   
• La donnée remittanceInformation doit intégrer la balise « unstructured » soit par exemple « remittanceInformation » : { « unstructured » : [ « test  » ] }..
   
• La donnée requestedExecutionDate ne peut pas être un week-end ou un jour target 2 pour les SCT. 
  Sinon, une erreur est générée et le paiement est rejeté. 
  Cette limitation ne s’applique pas pour les SCT immédiats uniquement si requestedExecutionDate est le jour même de la demande ; dans ce cas, le paiement sera transformé en un SCT différé programmé pour le jour ouvré suivant. 
  Pour les virements SCT permanents, la première échéance ne peut être positionnée :
  • 30 jours et plus après la date du jour ;
  • Le jour même.
     
• La donnée executionRule est facultative et ignorée si présente pour les SCT immédiats et différés. 
  Pour les virements SCT permanents, si elle est alimentée, elle ne peut être valorisée qu’avec la valeur « FWNG » (report au jour suivant). 
  L’ASPSP ne modifie pas la date d’exécution de sa propre initiative; celle positionnée par le TPP doit être une date acceptable pour la banque (cf. remarques sur donnée requestedExecutionDate).
   
• La donnée frequency ne doit être alimentée que pour les virements SCT permanents, elle est obligatoire dans ce cas. 
  Elle n’accepte que les valeurs MNTH (Monthly), QUTR (Quaterly) et YEAR (Annual). 
  La donnée endDate (date de dernière échéance) ne doit être alimentée que pour les virements SCT permanents :
  • Si elle est renseignée, elle doit correspondre à une échéance valide et dans le futur :
    • requestedExecutionDate + n mois si frequency = MNTH;
    • requestedExecutionDate + n trimestres si frequency = QUTR;
    • requestedExecutionDate + n années si frequency = YEAR;
       
  • Si non renseignée, elle doit être calculée :
    • requestedExecutionDate avec l’année qui vaut 2099
       
• La donnée localInstrument est à alimenter avec la valeur « INST » pour déclencher un SEPA Instant Payment (SCT Inst).
  • Ce type de virement occasionne des frais facturés au client en fonction des conditions tarifaires en vigueur applicables pour son segment de clientèle (IP PART ou IP B2B);
  • La banque du bénéficiaire doit être atteignable en IP;
  • Pour les clients professionnels et entreprises, les comptes émetteurs et les pays des bénéficiaires éligibles pour ce type de virement sont définis sur le contrat de flux IP B2B.
     
• La donnée localInstrument ne doit pas être présente pour les SCT immédiats, différés ou permanents.
   
• Seuls les IBAN complets sont supportés pour les données « Iban« , « debtorAccount » et « creditorAccount »
  • La présence de lettre minuscules dans les IBAN (et spécialement pour la donnée creditorAccount) est acceptée pour la prise en compte d’une demande d’initiation de paiement. 
    Cependant, pour ce qui concerne les Banques Populaires, la Banque de Savoie et la Banque Palatine, bien que le parcours client va se dérouler normalement jusqu’à la validation du virement par le PSU avec authentification forte, le virement sera in fine refusé par le SI des Banques Populaires qui ne supporte pas les IBAN possédant des lettres en minuscules. Un message d’erreur sera affiché au PSU sur le dernier écran de son parcours indiquant que son virement ne sera pas exécuté.
     
• Si présente, la donnée debtor.privateId.identification donne l’identifiant client Banque à Distance saisi par le PSU et fourni au TPP, en vue de faire son authentification auprès de l’ASPSP ; cela évite par conséquent un écran côté IHM ASPSP.
  • Pour les Banques Populaires, la Banque Palatine et la Banque Palatine, il est nécessaire de forcer cette donnée en majuscules.
     
• La donnée « successfulReportUrl » est obligatoire pour le mode d’authentification REDIRECT mis en œuvre et doit contenir :
  • la redirect URL
  • ainsi que le pkce : code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) + code_challenge_method = S256
  • et le séparateur « & » ( /!\ pas de « ? »)
     
• Si la donnée « unsuccessfulReportUrl » est renseignée, elle peut contenir le séparateur « & » (pas de « ? » ).
   
• Si la donnée « unsuccessfulReportUrl » n’est pas renseignée, c’est la donnée valorisée au niveau de « successfullReportUrl » qui sera utilisée.
   
• La donnée supplementaryData doit être alimentée avec la valeur « REDIRECT ».
   
• La donnée scaHint est ignorée pour l’instant => les exemptions d’authentification forte ne sont pas possibles.
   
• Le format autorisé pour la donnée creationDateTime est le format ISO8601.
  • Les trois expressions régulières autorisées sont :
    • YYYY-MM-DDTHH:MM:SS.SSS+HH:MM
    • YYYY-MM-DDTHH:MM:SS.SSS+HHMM
    • YYYY-MM-DDTHH:MM:SS.SSS
  • Z en fin de format signifie que l’heure est en UTC
  • Exemples :
    • 2019-11-12T00:00:00.000+02:00
    • 2019-11-12T00:00:00.000+0200
    • 2019-11-12T00:00:00.000
       
• La donnée « state » est obligatoire pour le mode d’authentification REDIRECT mis en œuvre : elle est propagée durant tout le parcours PISP.
   
• La donnée beneficiary.creditor.name est limitée 35 caractères.
   

Déclenchement des parcours fluides

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 :

• L’IBAN débiteur (debtorAccount) uniquement : déclenchement de l’identification du PSU avant une authentification forte unique en fin de parcours pour sceller le paiement
• L’IBAN débiteur (debtorAccount) et l’identifiant du PSU (privateId) : déclenchement d’une authentification forte unique en fin de parcours pour sceller le paiement

Notion de cut-off – heure limite pour passer un virement SCT immédiat

Le CUT-OFF correspond à l’heure limite à laquelle un établissement peut exécuter un virement. Cette heure limite prend en compte :

• Les délais de traitement interne
• Les CUTOFF des différents systèmes de compensation, eux-mêmes assujettis au CUT-OFF des différents systèmes de règlement (généralement TARGET2)

Dans le cas des SEPA CREDIT TRANSFER (SCT), l’exécution doit être effectuée au plus tard dans la date de règlement correspondant à la celle demandée par le donneur d’ordre. Il n’est pas permis de reporter cette date de règlement.

En conséquence, lorsque l’heure de CUT-OFF est dépassée, l’exécution est reportée à la date suivante possible. Les dates d’exécution et de règlement sont donc fonction de l’heure d’arrivée de la demande.

L’heure de cut-off pour demander un virement SCT à J avec une date de règlement à J est fixé à 11h00 heure locale française,

L’heure limite pour demander l’exécution d’un virement SCT à J avec une date de règlement à J+1 est fixé à 17h00 heure locale française

Pour rappel, l’heure locale française :

• Egale à GMT +2 pendant l’été,
• Egale à GMT +1 pendant l’hiver

Sur le choix de rendre obligatoire certains champs facultatifs de la norme

Le champ categoryPurpose permet d’empêcher les virements non-marchands vers des bénéficiaires inconnus (non-enregistrés sur la banque en ligne du client) lorsque le moyen d’authentification n’est pas assez fort (hors Secur’pass) : ce champ est nécessaire pour savoir si le paiement est un paiement « à la volée » ou non.

Le champ chargeBearer est obligatoire pour les paiements internationaux (i.e. en devise hors EUR) => les virements internationaux en devise ne sont pas disponibles.

Contrôle sur le bénéficiaire

Un contrôle additionnel est en place depuis le 7 décembre 2020 afin de rejeter la demande d’initiation de paiement :

• si le bénéficiaire est absent de la liste des bénéficiaires enregistrés par le client dans sa banque en ligne ;
• et si le champ categoryPurpose = « CASH » ;
• et si le moyen d’authentification forte utilisé n’est pas Secur’Pass.

Cas de rejet injustifié d’un SCT immédiat

Jusqu’à présent, pour les Banques Populaires, une demande d’initiation de paiement pour faire un SCT immédiat (virement pour le jour même) était rejeté les jours non ouvrés (samedi, dimanche, jours fériés, jour fermé au sens TARGET2).

A partir de fin octobre 2020, ces demandes ne seront plus rejetées (pour ce motif du moins) et seront transformé en SCT différé pour le jour ouvré suivant.

Cas de rejet pour les SEPA Instant Payment (SCTInst)

La banque du bénéficiaire doit être atteignable en Instant Payment.

Pour les Banques Populaires, un client qui s’identifie avec son identifiant ENTREPRISE doit avoir souscrit l’offre IP B2B pour émettre un SEPA Instant Payment. 

Par ailleurs, la liste des pays atteignables en IP est définie sur le contrat de flux IP B2B et les comptes éligibles au débit figurent doivent aussi être définis sur ce même contrat de flux.

Les SEPA Instant Payment ne sont pas reclassés en SCT immédiat lorsque l’une au moins de ces conditions n’est pas réunie => l’initiation de paiement est rejetée.

Codes erreur

Récupérer le statut d'une initiation de paiement

Cas d’usage

Cette méthode permet au PISP d’obtenir le statut d’une demande d’initiation de paiement précédemment envoyée à l’ASPSP, pour un PSU donné, via une requête de type POST /payment-requests.

Prérequis

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

Le TPP a déjà envoyé une requête qui a été enregistrée par l’ASPSP et à laquelle l’ASPSP a répondu avec un lien de localisation vers la demande d’initiation de paiement ou de virement sauvegardée.

Requête GET

Le point d’entrée dépendra du code établissement.

Vous devez insérer la même valeur des paramètres <cdetab> et <banque> que celle utilisée pour le jeton d’accès.

Pour rappel, la liste de nos établissements et les valeurs possibles des <cdetab> et <banque> sont précisées dans la rubrique « Limitations » .

Voici un extrait de cette liste :

Comme en mode test, le bon référentiel client est adressable via un « endpoint » au format www.<cdetab>.live.api.89c3.com ou www.<cdetab>.live.api.<banque>.fr

Pour exemple, nous avons donc comme URL de production :

• GET https://www.13807.live.api.89c3.com/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId} ou https://www.13807.live.api.banquepopulaire.fr/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId} pour récupérer le statut d’un paiement pour un client de la BPGO en production

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

Paramètre obligatoire paymentRequestResourceId : identifiant de la requête d’initiation de paiement pour laquelle on souhaite accéder au statut.

Résultat retourné

A la soumission de la requête et si toutes les données sont correctement formatées, une réponse (HTPP 200) vous sera retournée.

Cette réponse contiendra les données de l’initiation de paiement enrichies du statut de la requête d’initiation et du paiement associé.

Les valeurs possibles pour le statut de la demande de paiement sont les suivantes (valeurs pour la version STET v1.4.2.17) :

Le tableau suivant reprend les valeurs possibles pour le statut de l’initiation de paiement et de la transaction de paiement associée (valeurs pour la version STET v1.4.2.17) suite à une requête d’initiation de paiement :

Le tableau suivant reprend les valeurs possibles pour le statut de l’initiation de paiement et de la transaction de paiement associée (valeurs pour la version STET v1.4.2.17) suite à une requête d’annulation d’une initiation de paiement :

Exemples d’évolution du statut du virement

Exemple 1 :

• Une demande d’initiation de paiement est effectuée un jour ouvré à 16h,
• Comme la demande arrive avant 17h, le virement est exécuté le même jour (même si la date de règlement est positionnée à J+1) => un SCT de type immédiat est demandé pour exécution à J,
• La donnée creditTransferTransaction / transactionStatus est positionnée à PDNG dès la validation de l’initialisation du paiement.
   

Exemple 2 :

• Une demande d’initiation de paiement est effectuée un jour ouvré à 18h,
• Comme la demande arrive après 17h, le virement n’est pas programmé pour être exécuté le même jour => il est transformé en SCT différé et programmé pour le jour ouvré suivant, i.e. à J+1,
• La donnée creditTransferTransaction / transactionStatus est positionnée à ACSP dès la validation de l’initialisation du paiement,
• Le batch journalier de mise à jour du statut des virements qui sont dans un état non terminal est exécuté à 20h00. Ce batch met à l’état PDNG les virements prévu le même jour donc on a :
  • Le jour J de la demande d’initiation du paiement (de sa création à 24h00), le paiement reste à l’état ACSP puisqu’il est programmé pour le jour J+1,
  • A J+1, la donnée creditTransferTransaction / transactionStatus reste à l’état ACSP jusqu’au passage du batch à 20h00. A cette heure-là, la transaction pourrait passer à l’état PDNG
  • Mais comme entre-temps, le virement a été exécuté, il est possible (voire probable) qu’en fait le statut de la transaction soit directement passé de l’état ACSP à l’état ACSC.
     

Exemple 3 :

• Une demande d’initiation de paiement pour un paiement permanent mensuel est soumise le mercredi 26/02/2020 (2020-02-26T14:00:00.000+02:00) avec :
  • Une requestedExecutionDate le mercredi 04/03/2020 (2020-03-04T14:00:00.000+02:00) ;
  • Une endDate le lundi 04/05/2020 (2020-05-04T14:00:00.000+02:00) ;
  • Un executionRule non alimenté
• Les différents statuts obtenus seraient par exemple

Exemple 4 :

• Une demande d’initiation de paiement pour un SEPA Instant Payment est effectuée,
• La donnée creditTransferTransaction / transactionStatus est positionnée à ACSP dès la validation de l’initialisation du paiement,Dans les 10 secondes le virement est exécuté et le bénéficiaire est crédité sur son compte après soumission de la requête POST/paymentRequests/o-confirmation, la donnée creditTransferTransaction / transactionStatus passe à l’état ACSC dans les 20 secondes après la réponse du POST/paymentRequests/o-confirmation.

Exemple 5 :

• Pour les clients PRO et ENTREPRISE de la Banque Palatine qui utilisent la fonctionnalité du parapheur (Cyber ou mobile) pour valider leurs ordres, les virements SCT immédiats, permanents ou différés qui ont été soumis via une initiation de paiement, ne seront exécutés qu’une fois l’ordre correspondant validé dans le parapheur dans leur banque à distance.
• Après soumission de la requête POST /paymentRequests/o-confirmation, la donnée creditTransferTransaction / transactionStatus passe à « ACSP ».

Restitution de l’IBAN du compte débité

Depuis fin octobre 2020, l’IBAN du compte débité est systématiquement retourné par cette requête, même si cette donnée n’était pas présente dans la requête initiale de demande d’initiation de paiement.

Exemple

Requête :

GET /stet/psd2/v1.4.2/payment-requests/0000000386-155532845000030007970322

Résultat :

Status code : 200

Body

{ « paymentRequest »: { « resourceId »: « 0000000386-155532845000030007970322 », « paymentInformationId »: « TestBP041501C », « creationDateTime »: « 2019-04-15T12:56:11.122Z », « numberOfTransactions »: 1, « initiatingParty »: { « name »: « Mon marchand », « postalAddress »: { « country »: « FR », « addressLine »: [ « Copé Choux », « 44850 Mouzeil » ] }, « organisationId »: { « identification »: « 00987654321 », « schemeName »: « BANK », « issuer »: « FR » }, « privateId »: null }, « paymentTypeInformation »: { « instructionPriority »: « HIGH », « serviceLevel »: « SEPA », « localInstrument »: null, « categoryPurpose »: « CASH » }, « debtor »: { « name »: « Gaby Gallet Fourcade », « postalAddress »: { « country »: « FR », « addressLine »: [ « 25 rue de la Grange aux Loups », « 44000 Nantes » ] }, « organisationId »: null, « privateId »: { « identification »: « D0999993I0 », « schemeName »: « COID », « issuer »: « FR » } }, « debtorAccount »: { « iban »: « FR7613807008060732183304150 », « other »: null }, « debtorAgent »: { « bicFi »: « CCBPFRPPNAN », « clearingSystemMemberId »: null, « name »: null, « postalAddress »: null }, « beneficiary »: { « id »: « string », « isTrusted »: false, « creditorAgent »: { « bicFi »: « CCBPFRPPNAN », « clearingSystemMemberId »: null, « name »: null, « postalAddress »: null }, « creditor »: { « name »: « Camille Foucher », « postalAddress »: { « country »: « FR », « addressLine »: [ « 23 rue Fructidor », « 44000 Nantes » ] }, « organisationId »: null, « privateId »: { « identification »: « D0371101 », « schemeName »: « COID », « issuer »: « FR » }}, « creditorAccount »: { « iban »: « FR7613807000343142150215863 », « other »: null }}, « ultimateCreditor »: null, « purpose »: null, « chargeBearer »: « SLEV », « paymentInformationStatus »: « ACTC », « statusReasonInformation »: null, « fundsAvailability »: null, « booking »: false, « requestedExecutionDate »: « 2019-04-15T12:56:11.122Z », « creditTransferTransaction »: [ { « paymentId »: { « resourceId »: « 0000000386-155532845000130007219679 », « instructionId »: « TestBP041501C », « endToEndId »: « TestBP041501C » }, « requestedExecutionDate »: null, « endDate »: null, « executionRule »: null, « frequency »: null, « instructedAmount »: { « currency »: « EUR », « amount »: « 150 » }, « beneficiary »: null, « ultimateCreditor »: null, « regulatoryReportingCodes »: [ « string » ], « remittanceInformation »: [ « ma remittance » ], « transactionStatus »: null, « statusReasonInformation »: null } ], « supplementaryData »: { « acceptedAuthenticationApproach »: [ « REDIRECT » ], « appliedAuthenticationApproach »: « REDIRECT », « scaHint »: « noScaExemption », « successfulReportUrl »: « https://www.successful.fr », « unsuccessfulReportUrl »: « https://www.unsuccessful.fr » } }, « _links »: null }

Codes erreur

Annuler une initiation de paiement

Cas d’usage

Cette méthode permet au PISP d’annuler une demande d’initiation de paiement déjà enregistrée:

• Pour un SCT différé, à condition que le paiement n’ait pas encore été exécuté et que sa date d’exécution n’est pas atteinte (i.e. date d’exécution prévue au moins à J+1 par rapport à la date de demande d’annulation).
• Pour un SCT permanent, à condition que la date de l’échéance courante du paiement n’ait pas encore été atteinte (requestedExecutionDate recalculée à chaque fois qu’une échéance du paiement a été traitée) et que sa date de fin (endDate) n’a pas été atteinte (i.e. date d’exécution prévue au moins à J+1 par rapport à la date de demande d’annulation).

Autrement dit, cet appel permet d’envoyer à la banque (ASPSP) d’un client une demande d’annulation d’un paiement qui a été initié avec la méthode POST /payment-requests (voir la rubrique « Cas d’usage » > « Initier un paiement » ) et qui n’est pas encore échu.

Seule l’annulation d’un paiement SCT différé ou d’un SCT permanent unique en euros est possible.

Réciproquement un virement SCT qui a été initié via l’API DSP2 PISP (quelle que soit la version) est annulable uniquement via l’API DSP2 PISP. Autrement dit, on ne peut pas annuler sur l’application internet de la banque (Cyber) ou sur l’application mobile de la banque, un virement SCT qui a été initialisé via DSP2.

Prérequis

Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité pour le rôle TPP « PISP » (voir la rubrique « Eligibilité »), et d’avoir récupéré le jeton d’accès OAuth2 (voir la rubrique « Cas d'usage » > « Récupérer un jeton »).

Le TPP a déjà envoyé une requête DSP2 API PISP en version 1.4.2 qui a été enregistrée par l’ASPSP et à laquelle l’ASPSP a répondu avec un lien de localisation vers la demande de paiement / virement sauvegardée.

Corollaire : Pour annuler une initiation de paiement qui a été initiée par l’API DSP2 en version 1.4.0, il convient d’utiliser une requête DSP2 PISP en version 1.4.0 également (i.e. PUT /stet/psd2/v1/payment-requests/{resourceId}).

Requête PUT

Le point d’entrée dépendra du code établissement.

Vous devez insérer la même valeur des paramètres <cdetab> et <banque> que celle utilisée pour le jeton d’accès.

Pour rappel, la liste de nos établissements et les valeurs possibles des <cdetab> et <banque> sont précisées dans la rubrique « Limitations ».

Voici un extrait de cette liste :

Comme en mode test, le bon référentiel client est adressable via un « endpoint » au format www.<cdetab>.live.api.89c3.com ou www.<cdetab>.live.api.<banque>.fr

Pour exemple, nous avons donc comme URL de production :

• PUT https://www.13807.live.api.89c3.com/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId} ou https://www.13807.live.api.banquepopulaire.fr/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId} pour annuler un paiement pour un client de la BPGO en production

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

Paramètre obligatoire paymentRequestResourceId : identifiant de la requête d’initiation de paiement pour laquelle on souhaite annuler le virement.

La structure du body et les champs obligatoires sont décrits dans la norme STET. Le Tiers de Paiement peut et doit récupérer les informations de son virement avec la méthode GET/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId} afin de vérifier que le paiement est à un statut annulable.

Pour savoir si un virement est éligible, les informations suivantes doivent être valorisées dans la requête comme suit :

• La donnée paymentInformationStatus doit avoir l’une des valeurs : ACTC/ACCP/ACSP
   
• La donnée transactionStatus (au niveau de la transaction dans l’objet creditTransferTransaction) doit avoir la valeur : PDNG (si paymentInformationStatus = ACSP), sinon il ne doit pas être renseigné
   
• La donnée serviceLevel doit être renseigné à SEPA (seule les virements SEPA différés sont annulables)
   
• La donnée currency doit être renseignée à EUR => les virements internationaux en devise ne sont pas disponibles
   
• La requête doit contenir un seul paiement
   
• La donnée frequency ne doit être alimentée que pour les virements permanents.
   
• La donnée localInstrument ne doit pas être valorisée, seuls les SCT étant acceptés pour l’annulation
   
• La donnée requestedExecutionDate doit être dans le futur : à minima à J+1

Spécificités pour les virements unitaires

• La donnée numberOfTransactions est à 1 pour un virement unitaire => la requête doit contenir le virement unitaire transmis dans la requête d’initiation de paiement d’origine.

Spécificités pour les virements multiples (cette fonctionnalité sera disponible en février 2023)

• La donnée numberOfTransactions est comprise entre 2 et 50 au plus pour un virement multiple => la requête doit contenir le virement multiple transmis dans la requête d’initiation de paiement d’origine.
   
• L’annulation d’un virement multiple annule tous les virements unitaires qu’il contient.

Pour permettre à la banque de comprendre que la requête est une demande d’annulation d’une initiation de paiement, certaines informations doivent être modifiées dans la requête comme suit (API DSP2 STET_V1.4.2.17 Part 3 Interaction Examples p.23) :

• La donnée transactionStatus(au niveau de la transaction dans l’objet creditTransferTransaction) doit être positionnée à « CANC » (Annulé)
   
• La donnée paymentInformationStatus doit avoir la valeur « CANC » (Annulé).
   
• La donnée statusReasonInformation (au niveau de la transaction dans l’objet creditTransferTransaction) doit être positionnée avec l’une des valeurs suivantes :

• Il faut également enlever toute la partie _links
   
• Pour finir il faut supprimer l’intitulé du parent « paymentRequest »: { » ainsi que l’accolade fermante en bas du flux « } ».
   

Les autres données de la requête doivent être identiques à celles récupérées avec la méthode GET.

 

Résultat retourné

A la soumission de la requête, et si toutes les données sont correctement formatées, une réponse (HTPP 200) vous sera retournée. Cette réponse contiendra le resourceId du paiement, ainsi que le mode d’authentification SCA Redirect (seul mode disponible), l’URL de consentement en fonction de la banque du payeur (urlconsent_approval_URL) et le non rejeu.

Remarques :

• La donnée paymentRequestResourceId, essentielle pour pouvoir annuler un paiement, est incluse en tant que paramètre dans l’URL de consentement « consentApproval » renvoyée lors de l’initiation de paiement.
   
• Idem pour le non rejeu : c’est le paramètre nonce dans l’URL de consentement.
   

Codes erreur

Exemple

Requête :

PUT /stet/psd2/v1.4.2/payment-requests/00000032fa-159127166900013807464584

Body de Demande d’annulation v1.4.2
{ « resourceId »: « 00000032fa-159127166900013807464584 », « paymentInformationId »: « azertyui », « creationDateTime »: « 2020-06-04T13:54:29.148+02:00 », « numberOfTransactions »: 1, « initiatingParty »: { « name »: « Pisp Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Reaumur », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 12FR5 », « schemeName »: « COID », « issuer »: « ACPR » }, « privateId »: null }, « paymentTypeInformation »: { « instructionPriority »: null, « serviceLevel »: « SEPA », « localInstrument »: null, « categoryPurpose »: « DVPM » }, « debtor »: { « name »: « Customer Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Leclerc »,« 94512 Charenton-le-Pont »] }, « organisationId »: null, « privateId »: { « identification »: « D8183250I0 », « schemeName »: « BANK », « issuer »: « BICXYYTT512 » } }, « debtorAccount »: { « iban »: « FR7613685749843054784158595 », « other »: null }, « debtorAgent »: { « bicFi »: « CCBPFRPP512 », « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId » }, « name »: « Cpy Name », « postalAddress »: { « country »: « FR »,« addressLine »: [ « 512 rue De Gaulle », « 85000 LRSY »] } }, « beneficiary »: { « id »: null, « isTrusted »: null, « 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 » }, « privateId »: null }, « creditorAccount »: { « iban »: « FR7613825002000400000041717 », « other »: null } }, « ultimateCreditor »: null, « purpose »: « COMC », « chargeBearer »: « SLEV », « paymentInformationStatus »: « ACSP », « statusReasonInformation »: null, « fundsAvailability »: null, « booking »: null, « requestedExecutionDate »: « 2020-06-04T13:54:29.148+02:00 », « creditTransferTransaction »: [ { « paymentId »: { « resourceId »: « 00000032fa-159127166900113807942902 », « instructionId »: « instructionId 1591271669 », « endToEndId »: « endToEndId 1591271669 » }, « requestedExecutionDate »: null, « endDate »: null, « executionRule »: null, « frequency »: null, « instructedAmount »: { « currency »: « EUR », « amount »: « 2.12 » }, « beneficiary »: null, « ultimateCreditor »: null, « regulatoryReportingCodes »: [], « remittanceInformation »: [ « remittanceInformation01 » ], « transactionStatus »: « RJCT », « statusReasonInformation »: « DS02 » } ], « supplementaryData »: { « acceptedAuthenticationApproach »: [ « REDIRECT » ], « appliedAuthenticationApproach »: « REDIRECT », « scaHint »: « scaExemption », « successfulReportUrl »: « https://www.successful.fr », « unsuccessfulReportUrl »: « https://www.unsuccessful.fr » }}
Résultat :

Status code : 200

Body de la réponse :
{ « appliedAuthenticationApproach »: « REDIRECT », « _links »: { « consentApproval »: { « href »: « https://www.13807.live.api.89c3.com/89C3api/accreditation/v1.4.2/cancellation?paymentRequestResourceId=00000032fa-159127166900013807464584&nonce=RFxE0ywQmzW0Z68xJloN&creditorName=QW1hem9uIFNB&creditorAccount=RlI3NjEzODI1MDAyMDAwNDAwMDAwMDQxNzE3&amount=Mi4xMg%3D%3D¤cy=RVVS&successfulReportUrl=aHR0cHM6Ly93d3cuYXBpLjg5YzMuY29tLmZy&unsuccessfulReportUrl=aHR0cHM6Ly93d3cuYXBpLjg5YzMuY29tLmZyL25vdXMtY29udGFjdGVy&debtorAccount=RlI3NjEzODA3MDA4MDQzMDAxOTY1NDA1MTU4&privateId=RDgxODMyNTBJMA%3D%3D&requestedExecutionDate=MjAyMC0wNi0yNFQwOTowMTozMy44NTQrMDI6MDA%3D&method=UFVU »,« templated »: true } }}

Confirmer une initiation de paiement

Cas d’usage

Cette méthode, liée au mode d’authentification dit « redirect », permet au PISP de confirmer à l’ASPSP :

• Soit une demande d’initiation de paiement
• Soit une demande d’annulation d’une initiation de paiement

… en transmettant un facteur d’authentification du titulaire du compte débité afin que l’ASPSP puisse poursuivre la demande.

Seule la méthode POST /payment-requests/{paymentRequestResourceId}/o-confirmation qui correspond au mode d’authentification dit « redirect renforcé » est implémentée.

Cet appel permet d’envoyer à la banque (ASPSP) d’un client une demande de confirmation d’un paiement qui a été initié avec la méthode POST /payment-requests (voir la rubrique « Cas d’usage » > « Initier un paiement ») et qui a été validée par le PSU.

Ne sont pas implémentées les méthodes suivantes :

• POST /confirmation du « REDIRECT simple » (renvoie HTTP 405)
• Confirmation d’une annulation de demande de paiement car elle est est implicitement portée par l’acceptation par le PSU de la demande d’annulation en elle-même.

Prérequis

Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité pour le rôle TPP « PISP » (voir la rubrique « Eligibilité » ), et d’avoir récupéré le jeton d’accès OAuth2 (voir la rubrique « Cas d'usage » > « Récupérer un jeton » ).

Le TPP a déjà envoyé une requête qui a été enregistrée par l’ASPSP et à laquelle l’ASPSP a répondu avec un lien de localisation vers la demande de paiement / virement sauvegardée après que le PSU a validée le paiement.

Requête POST

Le point d’entrée dépendra du code établissement. Vous devez insérer la même valeur des paramètres <cdetab> et <banque> que celle utilisée pour le jeton d’accès.

Pour rappel, la liste de nos établissements et les valeurs possibles des <cdetab> et <banque> sont précisées dans la rubrique « Limitations » . Voici un extrait de cette liste :

Comme en mode test, le bon référentiel client est adressable via un « endpoint » au format www.<cdetab>.live.api.89c3.com ou www.<cdetab>.live.api.<banque>

Par exemple, nous avons donc comme URL de production :

• POST https://www.17515.live.api.89c3.com/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}/o-confirmation

ou

• POST https://www.13807.live.api.banquepopulaire.fr/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}/o-confirmation

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

Paramètre obligatoire paymentRequestResourceId : identifiant de la requête d’initiation de paiement pour laquelle on souhaite confirmer le virement.

La structure du body et les champs obligatoires sont décrits dans la norme STET :

• nonce => challenge à renvoyer par le TPP pour éviter de rejouer le processus d’authentification
• psuAuthenticationFactor => facteur d’authentification transmis par le TPP à la banque pour finaliser le processus d’authentification forte

Le tiers de paiement peut et doit récupérer les informations de son virement avec la méthode GET /stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId} afin de vérifier que le paiement a été validé par le client :

• La donnée paymentInformationStatus doit avoir la valeur : ACSP
• La donnée transactionStatus (au niveau de la transaction dans l’objet creditTransferTransaction) doit avoir la valeur : PDNG

Cas particulier du parapheur

Pour les clients PRO et ENTREPRISE de la Banque Palatine qui utilisent la fonctionnalité du parapheur (Cyber ou mobile) pour valider leurs ordres, les virements SCT immédiats, permanents ou différés qui ont été soumis via une initiation de paiement, ne seront exécutés qu’une fois l’ordre correspondant validé dans le parapheur dans leur banque à distance. Les virements SEPA Instant Payment (SCTInst) issus d’une initiation de paiement ne sont pas concernés à ce jour par le parapheur.

Résultat retourné

A la soumission de la requête, et si toutes les données sont correctement formatées, une réponse (HTTP 200) sera retournée.

Cette réponse contiendra le resourceId du paiement, ainsi que le mode d’authentification SCA Redirect (seul mode disponible), l’URL de consentement en fonction de la banque du payeur (urlconsent_approval_URL) et le non rejeu.

Remarques :

• La donnée paymentRequestResourceId, essentielle pour pouvoir confirmer un paiement, est incluse en tant que paramètre dans l’URL de consentement « consentApproval » renvoyée lors de l’initiation de paiement.
• Idem pour le non rejeu : c’est le paramètre nonce dans l’URL de consentement.

Codes erreur

Exemple

Requête :

POST /stet/psd2/v1.4.2/payment-requests/0000000a22-156688979900016807956016/o-confirmation

Body :
{ « nonce »: « 00000032fa-159127166900013807464584 », « psuAuthenticationFactor »: « azertyui »}
Résultat :

Status code : 200

Body de la réponse :
{

« paymentRequest » : {

« resourceId » : « 0000000a22-156688979900016807956016 »,

« paymentInformationId » : « MyPmtInfld123 »,

« creationDateTime » : « 2019-07-22T09:25:22.527+02:00 »,

« numberOfTransactions » : 1,

« debtorAgent » : {

« bicFi » : « CCBPFRPP512 »,

« name » : « B.P Grand Ouest »,

« postalAddress » : {

« country » : « FR »,

« addressLine » : [

« 15 Boulevard de la Boutière »,

« CS 26858 35768 SAINT GREGOIRE CEDEX »

]

}

},

« initiatingParty » : {

« name » : « MyPispName »,

« postalAddress » : {

« country » : « FR »,

« addressLine » : [

« 5 avenue Anatole France « ,

« 75007 PARIS »

]

},

« organisationId » : {

« identification » : « 12FR5 »,

« schemeName » : « COID »,

« issuer » : « ACPR »

}

},

« paymentTypeInformation » : {

« serviceLevel » : « SEPA »,

« categoryPurpose » : « CASH »

},

« debtor » : {

« name » : « Marc « ,

« postalAddress » : {

« country » : « FR »,

« addressLine » : [

« 512 rue de la coupe du monde »,

« 94512 Charenton-le-Pont »

]

},

« privateId » : {

« identification » : « D0999990I0 »,

« schemeName » : « BANK »,

« issuer » : « BICXYYTT512 »

}

},

« debtorAccount » : {

« iban » : « FR7613807008043001965405255 »

},

« beneficiary » : {

« creditorAgent » : {

« bicFi » : « CCBPFRPP512 »,

« name » : « B.P Grand Ouest »,

« postalAddress » : {

« country » : « FR »,

« addressLine » : [

« 15 Boulevard de la Boutière »,

« CS 26858 35768 SAINT GREGOIRE CEDEX »

]

}

},

« creditor » : {

« name » : « myMerchant »,

« postalAddress » : {

« country » : « FR »,

« addressLine » : [

« Place Charles de Gaulle »,

« 75008 PARIS »

]

},

« organisationId » : {

« identification » : « 852126790 »,

« schemeName » : « BANK »,

« issuer » : « FR »

}

},

« creditorAccount » : {

« iban » : « FR7613807008043001965406128 »

}

},

« purpose » : « COMC »,

« chargeBearer » : « SLEV »,

« paymentInformationStatus » : « PDNG »,

« statusReasonInformation » : null,

« fundsAvailability » : null,

« booking » : null,

« requestedExecutionDate » : « 2020-09-23T13:25:22.527+04:00 »,

« creditTransferTransaction » : [

{

« paymentId » : {

« resourceId » : « 0000000a22-146329369000016907660677 »,

« instructionId » : « MyInstrId123 »,

« endToEndId » : « MyEndToEndId123 »

},

« instructedAmount » : {

« currency » : « EUR »,

« amount » : « 327.12 »

},

« remittanceInformation » : [

« MyRemittanceInformation123 »

],

« transactionStatus » : « PDNG »

}

],

« supplementaryData » : {

« appliedAuthenticationApproach » : « REDIRECT »,

« scaHint » : « scaExemption »,

« successfulReportUrl » : « https://www.api.89c3.com »,

« unsuccessfulReportUrl » : « https://www.api.89c3.com »

}

}

}

Assemblage sandbox

Introduction – précisions sur les fonctionnalités de la sandbox

La sandbox BPCE API peut être utilisée de 2 manières 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 « Cas d'usage » > « Récupérer un 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 « Cas d'usage » > « Récupérer un 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) :

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

Image

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.

Image

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 :

Image

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.

Image

2) Le PSU est redirigé vers un premier écran d’authentification forte proposé par son établissement bancaire pour valider son identité.

Image

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:

Image

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

Image

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.

Image

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.

Image

4) Le PSU sélectionne et valide le compte à débiter.

Image

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
Image	Image

(*) 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) :

Image

2) Le PSU est redirigé vers un premier écran d’authentification forte proposé par son établissement bancaire pour valider son identité.

Image

Le code SMS pour authentification est à saisir ((voir la rubrique « Comment tester l’API ? » > « Testez nos persona »  pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires:

Image

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 :

GET https://www.13807.sandbox.api.89c3.com/stet/psd2/v1.4.2/payment-requests/0000000a22-156688979900016807956016

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:

POST https://www.13807.live.api.89C3.com/stet/psd2/v1.4.2/payment-requests/0000000a22-156688979900016807956016/o-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 :

{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 piement

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 :

PUT https://www.13807.sandbox.api.89C3.com/stet/psd2/v1.4.2/payment-requests/0000000a22-156688979900016807956016

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

Image

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.

Image

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 :

Image

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 :

Image

2) Le PSU est redirigé vers un écran d’authentification forte proposé par son établissement bancaire pour valider son identité.

Image

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:

Image

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.

Image

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.

Image

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,

Image

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.

8ème étape : Confirmer une demande d’annulation d’une initiation de paiement

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.

Tester nos persona

Conformément à la réglementation DSP2 (cf. RTS Art. 30 (5)), nous devons en tant qu’ASPSP mettre à disposition un dispositif d’essai comprenant une assistance et permettant des tests de connexion et de fonctionnement, afin que les TPP qui ont demandé l’agrément nécessaire puissent tester les logiciels et applications qu’ils utilisent pour proposer un service de paiement aux utilisateurs.

Cette page présente les jeux de données qui permettent de tester l’API :

• Des clients fictifs sont proposés par segment de clientèle (étudiant, cadre, entreprise, etc.) qui recouvrent des cas de clients PART, PRO et ENT :
  • 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 de personnalité 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.
  • Les catégories « professionnel » (PRO) et « entreprise » (ENT) couvrent les personnes morales.
     
• Les caractéristiques de leurs comptes et cartes à débit différé y sont déclinées (mono-compte, multi-comptes, multi-bancarisé, présence d’une carte à débit différé, solde du compte).
   
• Les données utiles attendues en entrée par les API y sont énumérées (identifiant banque à distance, code SMS pour les authentifications fortes, IBAN).

Les identifiants et données ci-dessous sont des données fictives et ne peuvent pas être utilisées en production.

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 :

Image

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 Groupe BPCE API Store dans la partie « Roadmap » de l’API impactée. 

Une communication via courriel vers les correspondants des prestataires enrôlés sur le portail BPCE API pourra venir compléter ce dispositif.

Planning des évolutions fonctionnelles à venir de l’API

L’API d’Information sur compte fait l’objet d’améliorations et d’évolutions continues tout au long de l’année*.

(*) NB : l’article 30 (4) des RTS précise que des changements significatifs de l’API peuvent intervenir sans délai. Nous appliquons cette clause dans les cas suivants :

• problème bloquant impactant de façon généralisée au moins l’un des segments de clients majeur (particuliers, professionnels, entreprises),
• problème de sécurité,
• évolutions demandées par les autorités nationales compétentes pour répondre à la trajectoire réglementaire.

Retrouvez ci-dessous notre roadmap prévisionnelle.

Limitations fonctionnelles

Limitations de cette API DSP2 en version 1.4.2

• S’applique à toutes les Banques Populaires.
   
• Ne s’applique qu’aux comptes de paiements en euros actifs et accessibles en ligne (cf. texte de la Directive DSP2).
   
• N’utilise que le mode d’authentification REDIRECTrenforcé (appel de la méthode o-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 unitaire en €uro (SCT)
  • Donc pas d’initiation de virement en devise.
  • Uniquement des virement SEPA SCT de type immédiat, permanent ou différé, ou des SEPA Instant Payment (SCTInst).
     
• 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.
   
• Les méthodes suivantes sont disponibles :
  • POST /payment-requests et POST /payment-requests/{paymentRequestRessourceId}/o-confirmation pour initier un paiement.
  • GET /payment-requests/{paymentRequestRessourceId} pour récupérer le statut d’une initiation de paiement.
  • La méthode PUT /payment-requests/{paymentRequestRessourceId} n’est supportée que pour annuler un virement SCT différé ou permanent.
     
• La méthode POST /payment-requests/{paymentRequestRessourceId}/confirmation 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.
   
• Si aucune action de l’utilisateur n’est effectuée au bout de 30 mns (04 minutes sur les écrans de redirection), cela 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 pour choisir le compte à 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 au moyen d’authentification forte en fonction du segment de clientèle

• 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 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 Enregistrement DSP2 » (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.<codetab>.live.api.89c3.com ou www.<codetab>.live.api.banquepopulaire.fr aligné sur le nom de domaine de l’accès direct www.banquepopulaire.fr.

Une fois choisi, ce point d’accès doit être conservé pour toutes les requêtes sous-jacentes.

Eligibilité

Les ressources de l’API « Initiation de paiements » ne peuvent être consommées que par des PSP ayant le rôle de Prestataires de Services d’initiation de Paiement (PISP). 

Ce statut est délivré par les autorités financières du pays dans lequel la demande est effectuée ; en France il s’agit de l’Autorité de Contrôle Prudentiel et de Résolution (ACPR), liée à la Banque de France.

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

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

PSDXX-YYYYYYYY-ZZZZZZZZ:

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

Cet identifiant OID est important à 2 titres :

• il servira à vous identifier lors des appels dans les requêtes des API STET (via le paramètre « client_id »)
• il devra être présent dans les certificats eIDAS que vous fournirez au teneur de compte (voir ci-dessous)

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

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

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

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

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

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

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 Groupe BPCE API Store. 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.4.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 et la v1.4.2 correspond à la version v1.4.2.17 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 :

Image

Versionning de l’API

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