Initier un paiement
Un de nos clients effectue une transaction sur un site d’e-commerce ou souhaite effectuer un virement ou un transfert.
Via cette API « Initiation de paiement » mise à disposition par la Banque BCP, vous pouvez soumettre en temps réel une demande d’initiation du paiement.
Le client connecté va être sollicité par sa banque pour valider l’opération.
Dans le cadre d’un parcours classique :
- Le PSU s’identifie et s’authentifie ;
- Puis, il sélectionne le compte de paiement disposant d’un solde suffisant pour le montant de l’opération ;
- Enfin, la banque scelle l’opération après que le client se soit à nouveau authentifié fortement pour valider l’opération.
Dans le cadre d’un parcours fluide, les données du compte débiteur sont transmises dans la requête d’initiation de paiement :
- Le PSU s’identifie si son identifiant n’est pas transmis dans la requête ;
- Puis, il vérifie les informations de l’opération ;
- Enfin, la banque scelle l’opération après que le client se soit authentifié fortement pour valider l’opération.
Cette API ne peut être consommée que par des prestataires ayant le rôle d’initiateurs de paiement (« PISP »), ce prérequis étant décrit dans voir la rubrique « Éligibilité« .
Une fois ce prérequis rempli, le processus global est le suivant :
1- Le client souhaite utiliser vos services afin de réaliser un virement ou un transfert, ou alors il sélectionne votre service lorsqu’il est sollicité par un e-commerçant pour régler son achat sur le site du e-commerçant. Il vous précise la Banque BCP dans lequel il est domicilié à travers vos interfaces.
2- Lors du premier échange avec les infrastructures du teneur de compte, vous allez faire une demande de jeton d’autorisation. Le principe de base est, qu’en tant que TPP PISP, vous devez obtenir ce jeton AVANT de consommer l’API. Ce jeton est généré par le teneur de compte (ASPSP) APRES avoir vous avoir identifié.
En tant que teneur de compte, nous allons :
- Vérifier vos certificats et agréments.
Pour cette API, il n’est pas nécessaire que nous identifions et authentifions fortement le client afin de récupérer son consentement et de générer le jeton d’accès.
3- Si nous avons pu vérifier votre identité et vos agréments, vous pourrez ensuite récupérer un jeton d’accès OAUTH2 via des échanges sécurisés avec la plateforme BPCE API (voir la rubrique « Vue d’ensemble » > « Récupérer votre jeton« ).
4- En présentant ce jeton d’autorisation valable uniquement pour cette opération, vous pourrez alors consommer l’API « initiation de paiement » afin :
- D’initier le paiement (voir la rubrique « Cas d’usage » > « Initier un paiement« ) ;
- De récupérer le statut de l’initiation de paiement (voir la rubrique « Cas d’usage » > « Récupérer le statut d’une initiation de paiement« ) ;
- De modifier une initiation de paiement (voir la rubrique « Cas d’usage » > « Annuler une initiation de paiement« )
- De confirmer une initiation de paiement (voir la rubrique « Cas d’usage » > « Confirmer une initiation de paiement – méthode o-confirmation« ).
Consommer l'API
La description des services proposés ci-après n’est que purement fonctionnelle. Les aspects techniques sont répertoriés dans les sections « Cas d’usage » qui sont plus détaillées.
Vous devez aussi être familier avec la terminologie DSP2 et les abrévations utilisées. Vous pouvez également utiliser la foire aux questions (FAQ), l’assistant virtuel ou le glossaire.
Prérequis
En tant que TPP, vous devez être accrédité par l’autorité de contrôle prudentiel et de résolution (ACPR 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 / paragraph 3.4.5.4
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.
Utiliser le fallback
Principe
Conformément à la réglementation, les établissements du groupe BPCE ont mis en place une interface dédiée aux prestataires de services de paiement : il s’agit des API REST DSP2 publiées.
Si les API DSP2 exposées sont défaillantes, le prestataire des services de paiements pourra utiliser la solution couvrant les « mesures d’urgence applicables à une interface dédiée » (ou « fallback ») dont le principe est le suivant :
Cette solution répond aux exigences règlementaires de la DSP2 (article 33 des RTS). Vous pourrez l’utiliser avec les mêmes conditions et pré-requis décrits dans la rubrique « Eligibilité« .
Roadmap
Retrouvez ci-dessous les éléments de notre trajectoire prévisionnelle :
| Version | Fonctionnalités | Sandbox
Date de déploiement BPCE API Dev Portal & Sandbox |
Live
Date de déploiement BPCE Live API Gateway |
| v1.0 | Fallback (*) | Non applicable | Fin Septembre 2019 |
(*) Fonctionnalités Principales :
- Utilisation par le TPP du même endpoint que l’interface dédiée. Il dépend donc du code établissement <cdetab> qui permet d’adresser le bon référentiel client.
- Un paramètre de requête (header « fallback:1 » présent ou absent) ajouté par le TPP permet de distinguer une requête « Fallback » d’une requête API via l’interface dédiée qui doit être utilisée systématiquement
- Authentification du TPP via authentification mutuelle TLS par un certificat eIDAS (QWAC)
- Sécurisation identique à celle d’un accès à la banque en ligne du PSU (même interface utilisée par le PSU qu’en accès direct, et mêmes moyens d’authentification du client)
- Dans le cadre de la montée en charge de l’usage de l’interface dédiée (API), il n’est pas mis en place de bascule dynamique : la solution fallback est toujours active
- La solution de fallback est une solution de secours ne devant pas être utilisée comme moyen principal d’accès pour proposer les services DSP2. Son usage en est monitoré et tout usage abusif par un/des TPP sera automatiquement reporté auprès de l’autorité nationale compétente.
Exemple
1. Dans le cas où les API DPS2 sont indisponible de façon imprévue ou le système tomberait en panne (voir critères dans le texte RTS Art. 33), le TPP peut alors envoyer la requête :
POST https://www.12579.live.api.89c3.com/stet/psd2/oauth/token
avec :
- son certificat eIDAS QWAC de production
- le paramètre header (fallback: »1″)
2. Si les vérifications sont positives, la page d’accès à la banque en ligne s’affichera
3. Le TPP doit utiliser ensuite les identifiants du PSU via sa méthode propriétaire
Pour plus de détails sur la requête POST, voir STET V1.4.0.47 / Part I / section 3.4.3.2 / page 22
Limites
Les contraintes de cette solution sont les suivantes :
- Pas de réutilisation du contexte de l’interface dédiée, ni du jeton d’accès valable 180 jours (AISP)
- L’identifiant du terminal accédant (TermId) doit être obligatoirement fourni, sinon l’accès aux pages d’identification/authentification sera bloqué
- Seules les fonctionnalités DSP2 présentes sur la banque en ligne (référence: banque à distance sur internet fixe – pas la banque sur mobile) sont accessibles via le fallback. Par exemple, les services de banque en ligne ne proposent pas de paiement e-commerce. Cette fonctionnalité PISP n’est donc pas disponible en mode fallback
- Le client utilisateur des services (PSU) doit être connecté à l’application du TPP (pas de possibilité de traitement batch AISP pour venir récupérer les données consenties du client). La DSP2 imposant également un renforcement des moyens d’authentification forte (AF/SCA) systématique pour les accès à la banque à distance/en ligne, les moyens d’authentification fournis aux clients PSU seront utilisés (liste non exhaustive) :
- Soft token
- OTP SMS
- Clé physique (pour les entreprises)
Console Try-it
Principe
En vous connectant sur le portail, vous pouvez :
- Faire appel à l’API « initiation de paiement » via un formulaire dans lequel vous sélectionnez votre application et le jeton d’authentification/d’accès
- Puis vous saisissez les paramètres de la méthode que vous souhaitez tester (soit headers, soit body) dont ceux mentionnés par une étoile sont obligatoires.
Une fois les paramètres saisis, vous pouvez lancer l’exécution de la requête : vous obtiendrez soit un résultat, soit une erreur.
L’utilisateur peut enchaîner les requêtes en sélectionnant le profil client soit pour les Banques Populaires, soit pour les Caisses d’Epargne à partir duquel il souhaite tester les méthodes, les fonctionnalités mises en oeuvre étant différentes en fonction de la banque (cf. rubrique « Limitations« ).
Version 1.4.2
A compter du 8 juillet 2020, le try-it ne sera possible que pour la version V1.4.2.
Si vous avez déjà effectué une demande de GoLive, vous devez alors créer une nouvelle application, puis sélectionner la nouvelle API STET V1.4.2.
Si vous n’avez PAS effectué de demande de GoLive, vous pouvez :
- soit modifier votre application existante pour l’associer à la nouvelle API STET V1.4.2.
- soit créer une nouvelle application, puis sélectionner la nouvelle API STET V1.4.2.
Aperçu du formulaire d’exécution Try-It
Le resource owner = « ClientBanquePopulaire » est à sélectionner pour les Banques Populaires.
Le resource owner = « ClientCaisseEpargne » est à sélectionner pour les Caisses d’Epargne.
Aperçu de l’écran de génération du jeton Oauth2
Cet écran est accessible lorsque l’on édite l’application (TPP PISP notre exemple) et il permet de générer ou éditer un jeton Oauth2 que l’on sélectionnera dans le formulaire d’exécution Try-It.
Initier un paiement avec le Try-it
Voici la description des différents paramètres pour initier une demande de paiement avec la méthode POST /payment-requests :
| Paramètre | Description | Type de données | Type de paramètre | Obligatoire |
| Authorization* | Jeton d’accès devant être fourni comme header | Chaîne de caractères | Header | Oui |
| PSU-IP-Address | Adresse IP utilisé par le PSU lors de la connexion au TPP
*obligatoire si le PSU est connecté mais non renseignée en cas d’accès batch |
Chaîne de caractères | Header | Non* |
| PSU-IP-Port | Port IP utilisé par le PSU lors de la connexion au TPP | Chaîne de caractères | Header | Non |
| PSU-HTTP-Method | Méthode http utilisée lors de la requête la plus pertinente faite par le PSU vers le TTP | Chaîne de caractères | Header | Non |
| PSU-Date | Timestamp utilisé lors de la requête la plus pertinente faite par le PSU vers le TTP | Chaîne de caractères | Header | Non |
| PSU-GEO-Location | Localisation géographique du PSU fournie par le terminal mobile du PSU au TPP si elle existe | Chaîne de caractères | Header | Non |
| PSU-User-Agent | Header « User-Agent » envoyé par le PSU lors de la connexion au TPP | Chaîne de caractères | Header | Non |
| PSU-Referer | Header « Referer » envoyée par le PSU lors de la connexion au TPP. Il est à noter que dans des spécifications antérieures des RFC 1945 on préconise le nom « referer » (mal orthographié). Le nom « referrer » peut être utilisé au risque de ne pas être compris | Chaîne de caractères | Header | Non |
| PSU-Accept | Header « Accept » envoyé par le PSU au TPP lors de la connexion | Chaîne de caractères | Header | Non |
| PSU-Accept-Charset | Header « Accept-Charset » envoyé par le PSU au TPP lors de la connexion | Chaîne de caractères | Header | Non |
| PSU-Accept-Encoding | Header « Accept-Encoding » envoyé par le PSU au TPP lors de la connexion | Chaîne de caractères | Header | Non |
| PSU-Accept-Language | Header « Accept-Language » envoyé par le PSU au TPP lors de la connexion | Chaîne de caractères | Header | Non |
| PSU-Device-ID | UUID (Universally Unique Identifier) du périphérique utilisé par le PSU, si disponible | Chaîne de caractères | Header | Non |
| Digest* | donnée de la requête | Chaîne de caractères | Body | Oui |
| Signature* | Signature http de la requête (voir https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) La partie keyId du header devrait avoir le format suivant keyId= »SN=XXX,CA=YYYYYYYYYYYYYYYY » où « XXX » est le numéro de série en hexadécimal sans aucun préfixe (comme 0x, du certificat QSEAL dont la clé privée a servi pour la signature de celui-ci
« YYYYYYYYYYYYYYYY » est l’émetteur DN, nom complet de l’autorité de certification ayant émise ce certificat HTTP400 qui sera renvoyé par le serveur dans le cas d’une signature invalide ou absente. |
Chaîne de caractères | Header | Oui |
| X-Request-ID* | Header de corrélation à paramétrer dans la requête et devant être récupéré dans la réponse à celle-ci | Chaîne de caractères | Header | Oui |
Pour les paramètres de type de données « body », il est possible de copier-coller un exemple dans le formulaire (à droite de l’écran) grâce à la petite loupe bleue présente dans la description des paramètres en entrée de la requête, en changeant juste les valeurs spécifiques :
Cette loupe déploie une fenêtre avec le modèle du swagger.
La fourniture d’un objet paymentRequest en exemple n’est malheureusement pas fourni dans le swagger.
Si un exemple de cette ressource avait été présent dans le swagger fourni par la STET, il serait alors possible de cliquer sur la flèche rose située en bas de cette fenêtre pour que les données de l’exemple alimentent la fenêtre du Try-It située sur la droite. A noter, l’exemple provient de STET, nous vous signalons qu’il comporte une erreur dans les codes schemeName utilisés.
Un exemple de requête est donné ci-après, les données suivantes devant être unique et donc modifiées à chaque appel, sans quoi la requête est rejetée pour cause de doublon (le rejeu n’est pas autorisé) :
- paymentInformationId
- instructionId
- endToEndId
- x-request-id
{
« paymentInformationId »: « azertyui 1631195080 »,
« creationDateTime »: « 2021-09-12T10:45:09.209+02:00 »,
« numberOfTransactions »: 1,
« requestedExecutionDate »: « 2021-09-13T14: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 »: « FR7613825003000400000541718 »
}
},
« chargeBearer »: « SLEV »,
« creditTransferTransaction »: [
{
« purpose »: « COMC »,
« paymentId »: {
« instructionId »: « instructionId 1631195080 »,
« endToEndId »: « endToEndId 1631195080 »
},
« instructedAmount »: {
« currency »: « EUR »,
« amount »: « 2.71 »
},
« remittanceInformation »: {
« unstructured » : [ « remittanceInformation01 » ]
}
}
],
« supplementaryData »: {
« acceptedAuthenticationApproach »: [
« REDIRECT »,
« DECOUPLED »
],
« scaHint »: « scaExemption »,
« successfulReportUrl »: https://www.api.89c3.com/OAuth2Callback.aspx&state=OK-12345&code_challenge_method=S256&code_challenge=T3LPv9JWu_HtyEQOkDCo4YYRmZJXTjJ0Ng9jfq_UBBg,
« unsuccessfulReportUrl »: « https://www.api.89c3.com »
}
}
Suite à l’alimentation des paramètres obligatoires, la requête peut être soumise via la bouton « Exécuter, le résultat est alors visible sous ce bouton :
RESULTAT
Status code : 201
{ « appliedAuthenticationApproach »: « REDIRECT », « _links »: { « consentApproval »: { « href »: « TPPPISPurlConsentApproval/psuId.html?resourceId=0000000a22-146329369000016907660677&nonce=Id-2ed9775ce61639e9a3c94ecc », « templated »: null } }}
Il est également possible de visualiser les données retournées dans le header en déroulant la fenêtre Entête :
access-control-allow-origin: https://sandbox.api.89c3access-control-expose-headers: x-correlationidcache-control: no-cache, no-store, max-age=0, must-revalidate, publicconnection: closecontent-length: 218content-type: application/hal+json;charset=utf-8date: Thu, 13 March 2019 12:50:53 GMTexpires: 0max-forwards: 5pragma: no-cacheserver: Apachestrict-transport-security: max-age=63072000; includeSubdomains;via: 1.0 bilmwsg011.dom101.mapres ()x-content-type-options: nosniffx-correlationid: Id-2ed9775ce61639e9a3c94ecc 0x-frame-options: SAMEORIGIN, DENYx-nonce: Id-2ed9775ce61639e9a3c94eccx-xss-protection: 1; mode=block
Ecrans de la redirection ASPSP pour choix du compte à débiter et confirmation de l’initiation de paiement
Suite à la demande d’initiation de paiement (POST /payment-requests), il est possible de recopier l’URL contenu dans l’objet « consentApproval / href » de la réponse et de l’ouvrir dans un navigateur internet. Cela permet de faire jouer les écrans ASPSP de l’initiation de paiement.
Récupérer le statut d’une initiation de paiement avec le Try-it
Pour restituer le statut d’une initiation de paiement avec la méthode GET /payment-requests/{paymentRequestResourceId} , il est nécessaire de passer :
- en argument paymentRequestResourceId la valeur du champ de nom « resourceId » obtenu dans l’objet « consentApproval / href » en réponse de la méthode POST /payment-requests
- le même x-request-id que celui utilisé pour la méthode POST /payment-requests
RESULTAT
Status code : 200
{
« paymentRequest »: {
« resourceId »: « 0000000a22-146329369000016907660677 »,
« paymentInformationId »: « azertyui 1631195853 »,
« creationDateTime »: « 2021-09-12T10:45:09.209+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 »
]
}
},
« 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 »: « FR7613825003000400000541718 »
}
},
« chargeBearer »: « SLEV »,
« paymentInformationStatus »: « PDNG »,
« requestedExecutionDate »: « 2021-09-13T15:10:10.109+02:00 »,
« creditTransferTransaction »: [
{
« paymentId »: {
« resourceId »: « 0000000a22-146329369000016907660677 »,
« instructionId »: « instructionId 1631195080 »,
« endToEndId »: « endToEndId 1631195080 »
},
« requestedExecutionDate »: « 2021-09-13T15:10:10.109+02:00 »,
« instructedAmount »: {
« currency »: « EUR »,
« amount »: « 2.71 »
},
« purpose »: « COMC »,
« regulatoryReportingCodes »: [],
« remittanceInformation »: {
« unstructured »: [
« remittanceInformation01 »
]
},
« transactionStatus »: « PDNG »
}
],
« 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 »
}
},
« _links »: {
« request »: {
« href »: « /stet/psd2/v1.4.2/payment-requests/0000000a22-146329369000016907660677 »,
« templated »: false
},
« confirmation »: {
« href »: « /stet/psd2/v1.4.2/payment-requests/0000000a22-146329369000016907660677/o-confirmation »,
« templated »: false
}
}
}
Annuler une initiation de paiement avec le Try-it
La description des différents paramètres pour annuler une initiation de paiement avec la méthode PUT /payment-requests/{paymentRequestResourceId} sont les mêmes que ceux pour la méthode GET /payment-requests/{paymentRequestResourceId}
Il est nécessaire de passer :
- en argument paymentRequestResourceId la valeur du champ de nom « resourceId » obtenu dans l’objet « consentApproval / href » en réponse de la méthode POST /payment-requests.
- le même x-request-id que celui passé pour la méthode POST /payment-requests.
Pour constituer le body d’annulation d’un paiement, il convient de :
- Avoir effectuer une requête POST /payment-requests en prenant soin d’indiquer une date d’exécution postérieure à J+2 car on ne peut pas demander une annulation pour le même jour que la date d’exécution prévue pour un virement (donc ne pas mettre la date du jour à ce stade)
- Effectuer une requête GET /payment-requests/{paymentRequestResourceId},
- Recopier le body de réponse
- Effectuer les modifications suivantes sur ce body :
- La donnée transactionStatus de l’objet creditTransferTransaction doit être passée à « RJCT » (rejeté)
- La donnée statusReasonInformation de l’objet creditTransferTransaction doit être passée à « DS02 » (annulation client)
- Il faut également enlever toute la partie _links
- Pour finir il faut supprimer l’objet parent (niveau 1) « paymentRequest »: { » ainsi que l’accolade fermante en bas du flux « } »
Un exemple de requête est donné ci-après, 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.
{
« resourceId »: « 0000000a22-146329369000016907660677 »,
« paymentInformationId »: « azertyui 1631195853 »,
« creationDateTime »: « 2021-09-12T10:45:09.209+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 »
]
}
},
« 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 »: « FR7613825002000400000041717 »
}
},
« chargeBearer »: « SLEV »,
« paymentInformationStatus »: « PDNG »,
« requestedExecutionDate »: « 2021-09-13T15:10:10.109+02:00 »,
« creditTransferTransaction »: [
{
« paymentId »: {
« resourceId »: « 0000000a22-146329369000016907660677 »,
« instructionId »: « instructionId 1631195080 »,
« endToEndId »: « endToEndId 1631195080 »
},
« requestedExecutionDate »: « 2021-09-13T15:10:10.109+02:00 »,
« instructedAmount »: {
« currency »: « EUR »,
« amount »: « 2.71 »
},
« 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 »
}
}
Suite à l’alimentation des paramètres obligatoires, la requête peut être soumise via la bouton « Exécuter, le résultat est alors visible sous ce bouton :
Remarque : seules les initiations de paiement dans l’état ACTC or ACCP peuvent être annulées via une requête PUT /stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}
RESULTAT
Status code : 200
{ « appliedAuthenticationApproach »: « REDIRECT », « _links »: { « consentApproval »: { « href »: « https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v1/cancellation?paymentRequestResourceId=00000046cf-160008779100013807600254&nonce=jWyvLAU8PNm34YCOidrg&creditorName=QW1hem9uIFNB&creditorAccount=RlI3NjEzODI1MDAyMDAwNDAwMDAwMDQxNzE3&amount=Mi4xMg%3D%3D¤cy=RVVS&successfulReportUrl=aHR0cDovL3R1cmJvc2EuYmFucXVlcG9wdWxhaXJlLmZyLw%3D%3D&unsuccessfulReportUrl=aHR0cHM6Ly93d3cuYXBpLjg5YzMuY29tL2ZyL2NvbXBvbmVudC9icGNlcG9ydGFsL3Byb2R1Y3RzLzgwL3VzZWNhc2VzLzIyMQ%3D%3D&privateId=RDgxODMyNTBJMA%3D%3D&requestedExecutionDate=MjAyMC0wOS0yNFQwMTowMDowMC4wMDArMDI6MDA%3D&method=UFVU », « templated »: true } }}
Il est également possible de visualiser les données retournées dans le header en déroulant la fenêtre Entête :
access-control-allow-origin: https://www.api.89c3.com access-control-expose-headers: x-correlationidcache-control: no-cache, no-store, max-age=0, must-revalidate, publicconnection: Keep-Alivecontent-length: 178content-type: application/hal+json;charset=utf-8date: Mon, 14 Sep 2020 10:15:19 GMTexpires: 0keep-alive: timeout=5, max=299max-forwards: 20pragma: no-cachestrict-transport-security: max-age=63072000; includeSubdomains;x-content-type-options: nosniffx-correlationid: Id-b8425f5fd86fda545f6b2225 0x-frame-options: SAMEORIGIN, DENYx-request-id: 1x-xss-protection: 1; mode=block
Ecrans de la redirection ASPSP pour confirmation de l’annulation de l’initiation de paiement
Suite à la demande d’initiation de paiement (POST /payment-requests), il convient de recopier l’URL contenu dans l’objet « consentApproval / href » de la réponse et de l’ouvrir dans un navigateur internet. Cela permet de jouer les écrans ASPSP de confirmation de l’annulation du virement différé.
Assemblage sandbox
Introduction – précisions sur les fonctionnalités de la sandbox
La sandbox BPCE API peut être utilisée de 2 manières :
- Via le Try-it du portail BPCE-API (voir la rubrique « Comment tester l’API ? » > « Console Try-it« )
- Directement via votre application en appelant l’API « Initiation de paiement » de la plateforme BPCE API (assemblage sandbox)
En assemblage sandbox, il y a deux types d’appel :
- Le premier pour récupérer le jeton d’autorisation (voir la rubrique « Vue d’ensemble » > « Récupérez votre jeton« ) ;
- Le second pour faire l’appel à l’API « Initiation de paiement » (voir les cas d’usage « Initier un paiement« , « Récupérer le statut d’une initiation de paiement« , « Confirmer une initiation de paiement » et « Annuler une initiation de paiement »).
Limitations en environnement sandbox :
- Le cas d’usage « Annuler une initiation de paiement », n’est pas totalement testable dans l’environnement sandbox car cette méthode nécessite un croisement des données dynamiques alors que notre sandbox a un comportement statique :
- Les requêtes d’annulation d’une initiation de paiement sont acceptées dès que le format de la requête est correct (l’identifiant de l’initiation de paiement étant supposé exister).
Votre application consommatrice de l’API « Initiation de paiement » en assemblage sandbox va devoir récupérer un jeton d’accès via sa clé d’authentification auprès de l’AS (Authentification Server).
Ainsi votre application pourra consommer les méthodes « POST /payment-requests« , « GET /payment-requests/{payementRequestResourceId}« , « POST /payment-requests/{payementRequestResourceId}/o-confirmation » et « PUT /payment-requests/{payementRequestResourceId} » grâce à son jeton d’accès.
Les appels des méthodes de l’API pourront être enchaînés :
- En exécutant la requête de création du paiement « POST /payment-requests ».
- Puis, en exécutant la requête de récupération du statut du paiement « GET /payment-requests/{paymentRequestResourceId} en passant en paramètre le « paymentRequestResourceId » récupéré du résultat de la première requête.
- Puis, en exécutant la requête de confirmation du paiement « POST /payment-requests/{paymentRequestResourceId}/o-confirmation » en passant en paramètre le « paymentRequestResourceId » récupéré du résultat de la première requête.
- Puis, en exécutant la requête d’annulation du paiement « PUT /payment-requests/{payementRequestResourceId} » en passant en paramètre le « paymentRequestResourceId » et le body modifié récupéré du résultat de la seconde requête.
Les données utilisées pour faire les tests seront issues des personas (voir la rubrique « Comment tester l’API ? » > « Testez nos persona« ), ce qui permettra de choisir des profils spécifiques selon les tests de façon à mieux appréhender les résultats obtenus.
Prérequis
Vous devez déclarer votre APP sur le portail BPCE API (cf. menu « Mes applications« ) et nous transmettre les clés publiques de vos certificats QWAC et QSEALC de test afin que nous puissions :
- Déclarer votre APP comme application consommatrice de l’API ;
- Intégrer vos clés publiques QWAC et QSEALC dans nos infrastructures ;
- Récupérer et contrôler votre organizationId et votre rôle « PISP » dans notre registre des TPP.
Rappel : en tant que TPP, vous devez être accrédité par l’une des autorités compétentes nationales européennes (ACPR en France) pour le rôle d’initiateur de paiement (« PISP »).
Enchaînement des étapes pour tester l’accès à l’API PISP depuis votre APP
1ère étape : Récupérer un jeton d’accès
Cet appel vous permet de récupérer le jeton forgé par le serveur d’authentification de l’établissement et qui un prérequis pour chaque accès à l’une des méthodes de l’API d’initiation de paiement.
La description de la fonctionnalité et des champs de la requête est décrite dans la rubrique « Vue d’ensemble » > « Récupérez votre jeton« .
Afin de pouvoir interroger le bon backend, dans le parcours client, il est nécessaire que vous prévoyiez d’interroger le client au préalable sur son établissement de rattachement.
Pour l’accès à l’assemblage sandbox, le point d’entrée dépend du code établissement : www.<cdetab>.sandbox.api.89c3.com
Les seuls établissements bancaires utilisables en assemblage sandbox pour cette API sont les suivants (code établissement <cdetab> utilisé dans les URL) :
| Code établissement | Nom de l’établissement | Nom abrégé |
| 13807 | B.P Grand Ouest | BPGO |
| 13807 | CMM Grand Ouest | CMMGO |
| 17515 | Caisse d’Epargne Ile De France | CEIDF |
| 12579 | Banque BCP | BBCP |
Requête :
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/oauth/token
Dans les headers :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
Dans les params :
client_id : PSDFR-ACPR-12345
grant_type : client_credentials
scope : pisp
Remarques sur l’alimentation des champs :
<cdetab> => code établissement des deux banques disponibles dans cet environnement soit :
13807 (Banque Populaire Grand Ouest) ;
17515 (Caisse d’Epargne Ile de France).
client_id :
Si l’enregistrement du TPP a été réalisé au travers du processus de « GoLive » via notre portail BPCE API.
=> numéro d’agrément donné par votre autorité compétente (PSDXX-YYYYYYYY-ZZZZZZZZ)
Ou si l’enregistrement du TPP a été réalisé via l’API registerclient_id retourné dans la réponse au POST /register
=> client_id retourné dans la réponse au POST /register
grant_type => non modifiable = « client_credentials »
Réponse :
{
« access_token » : « firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz »,
« token_type » : « Bearer »,
« expires_in » : « 3600 »,
« scope » : « pisp »
}
Remarques sur l’alimentation des champs :
access_token => tokenCredential à transmettre dans le header authorization des requête de l’API d’initiation de paiement après le Bearer XX.
expires_in => durée de validité du token en secondes.
2ème étape : Initier un paiement
Cet appel vous permet d’initier un paiement en demandant au PSU connecté de donner son consentement pour le paiement.
La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Initier un paiement« .
Rappel : la méthode d’authentification supportée par l’établissement bancaire est le mode REDIRECTrenforcé => les cinématiques des enchaînements des écrans d’identification et d’authentification forte décrites ci-après correspondent à ce mode d’authentification.
Pour l’accès à l’assemblage sandbox, le point d’entrée est identique : www.<cdetab>.sandbox.api.89c3.com
Requête :
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/v1.4.2/payment-requests
Authorization : Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Headers :
Content-Type : application/json
Signature : keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_<empreinte-sha256>\« , algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\ »
X-Request-ID : MyXrequestId123
Body :
{ « paymentInformationId »: « MyPmtInfld123 », « creationDateTime »: « 2021-09-05T09:25:22.527+02:00 », « numberOfTransactions »: 1, « requestedExecutionDate »: « 2021-09-06T14:10:10.109+01:00 », « debtorAgent »: { « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId » }, « bicFi »: « CCBPFRPP512 », « name »: « Cpy Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue De Gaulle », « 85000 LRSY » ] } }, « initiatingParty »: { « name »: « Pisp Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Reaumur », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 12FR5 », « schemeName »: « COID », « issuer »: « ACPR » } }, « paymentTypeInformation »: { « serviceLevel »: « SEPA », « categoryPurpose »: « DVPM » }, « debtor »: { « name »: « Customer Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Leclerc », « 94512 Charenton-le-Pont » ] } }, « beneficiary »: { « creditor »: { « name »: « Amazon SA », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 avenue Maupassant », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 852126790 », « schemeName »: « BANK », « issuer »: « FR » } }, « creditorAgent »: { « name »: « Creditor Name », « bicFi »: « CCBPFRPP512 », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue de la primaube », « 12512 RODEZ » ] }, « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId! » } }, « creditorAccount »: { « iban »: « FR7613825002000400000541718 » } }, « chargeBearer »: « SLEV », « creditTransferTransaction »: [ { « purpose »: « COMC », « paymentId »: { « instructionId »: « instructionId 1630919339 », « endToEndId »: « endToEndId 1630919339 » }, « instructedAmount »: { « currency »: « EUR », « amount »: « 2.41 » }, « remittanceInformation »: { « unstructured » : [ « remittanceInformation01 » ] } } ], « supplementaryData »: { « acceptedAuthenticationApproach »: [ « REDIRECT » ], « scaHint »: « scaExemption », « successfulReportUrl »: https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK- 12345&code_challenge_method=S256&code_challenge=ABCD } }
Remarques sur l’alimentation des champs :
Authorization : Bearer => access_token récupéré pour le tokenCredential
Les données suivantes devant être unique, sans quoi la requête est rejetée pour cause de doublon (le rejeu n’est pas autorisé) :
– paymentInformationId ;
– instructionId ;
– endToEndId ;
– x-request-id.
debtor/privateId/identification => identifiant d’accès à la banque à distance pour le PSU : lorsqu’il est renseigné et que debtorAccount est renseigné, l’appel à l’écran d’identification du PSU n’est pas effectué.
debtorAccount => IBAN du PSU : lorsqu’il est renseigné, le seul compte sélectionnable pour le PSU est celui qui correspond à cet IBAN, pour peu que le compte soit éligible aux virements PISP.
Les fonctionnalités mises en œuvre peuvent différer entre les Banques Populaires et les Caisses d’Epargne (cf. cas d’usage « Initier un paiement« ).
Réponse :
{
« appliedAuthenticationApproach » : « REDIRECT »,
« _links » : {
« consentApproval » : {
« href » : »https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v2/identificationPisp?paymentRequestResourceId=00000000a22-156688979900016807956016&nonce=qJammuGI0OGCwznaZ0YO”,
« templated » : true
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 201 OK
Remarques sur l’alimentation des champs :
paymentRequestResourceId => identifiant à passer à la requête GET /payment-requests pour récupérer le statut de l’initiation de paiement
appliedAuthenticationApproach » = « REDIRECT » => seule valeur autorisée
href => URL de la page de redirection vers les écrans d’identification et d’authentification de l’établissement
nonce => anti rejeu technique
currency => récupérée du body passé en entrée
successfulReportUrl => récupérée du body passé en entrée
unsuccessfulReportUrl => récupérée du body passé en entrée
iban => récupérée du body passé en entrée
creditorName => récupérée du body passé en entrée
X-Request-ID: transmis en entrée
3ème étape : La redirection vers les écrans pour que le PSU valide le paiement
Cinématique nominale des enchaînements des écrans d’identification et d’authentification forte
Déroulé de l’enchaînement des écrans d’identification et d’authentification forte :
A partir de l’URI retournée dans « consentApproval« , il est possible de jouer l’enchaînement des écrans.
1) Le PSU est redirigé vers un écran d’identification proposé par son établissement bancaire et dans lequel il saisira son identifiant de banque à distance.
Attention : l’appel à cet écran ne peut être effectué qu’une seule fois
=> le nonce transmis dans l’URL permettant d’accéder à cet écran n’est utilisable qu’une seule fois (il est grillé en suite par l’anti-rejeu)
=> si l’application du TPP ou le PSU ne déroule pas l’ensemble du process en une fois, une nouvelle demande d’initiation de paiement (paymentRequest) sera nécessaire.
L’identifiant de banque à distance du PSU est à saisir (voir rubrique « Comment tester l’API? » > « Tester nos persona » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires :
Remarque : Le bouton « Mémoriser mon identifiant » n’est pas opérationnel. L’activer ne sert à rien.
Pour les Caisses d’Epargne, si le PSU est un professionnel ou une entreprise, il devra saisir son numéro d’usager en plus de son identifiant de banque à distance.
2) Le PSU est redirigé vers un premier écran d’authentification forte proposé par son établissement bancaire pour valider son identité.
Le code SMS pour authentification est à saisir (voir rubrique « Comment tester l’API? » > « Tester nos persona » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires:
En production live : La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du PSU par l’établissement bancaire (SMS OTP, secur’pass, etc.).
Elle dépend aussi de l’équipement du PSU sur lequel tourne l’application du PISP utilisée par le PSU (PC ou mobile/smartphone/tablette).
Note : en environnement de sandbox, le code SMS à saisir est systématiquement : « 12345678 »
3) Le PSU est redirigé vers un écran de sélection de son compte à débiter proposé par son établissement bancaire.
Exemple de restitution pour le persona « Marc » des Banques Populaires qui dispose de 4 comptes (voir rubrique « Comment tester l’API? » > « Tester nos persona » pour les jeux de données de l’établissement) :
NB : Si le PISP fournit l’IBAN du PSU à débiter dans sa requête (champ « debtorAccount »), seul le compte correspondant sera sélectionnable et proposé au PSU : exemple ci-dessous pour le persona Tech’n Co des Banques Populaires.
NB : Si le PSU ne dispose pas de compte, la requête d’initiation de paiement ne va pas aboutir et le PSU va être redirigé vers votre APP. Exemple pour le persona « Thomas » des Banques Populaires.
4) Le PSU sélectionne et valide le compte à débiter.
5) Le PSU est redirigé vers un second écran d’authentification forte proposé par son établissement pour valider son paiement.
Ecrans identiques à l’écran d’authentification forte de l’étape (2) pour valider l’identité du PSU, hormis l’écran de saisi du mot de passe qui n’est pas représenté.
Des exemptions sont possibles pour l’étape d’AF pour valider le paiement => cette possibilité n’est pas disponible.
Le PISP peut renseigner un indicateur lui permettant d’indiquer qu’il considère la demande de paiement comme étant un cas d’exemption d’authentification forte. La décision finale d’appliquer ou non une exemption d’authentification forte reste à l’appréciation de l’ASPSP.
Les cas de dérogation à l’obligation d’authentification forte du PSU si les exigences générales en matière d’authentification sont remplies sont décrits dans l’article 2 des RTS de la DSP2.
6) Le PSU est redirigé vers l’APP du PISP.
Le PISP fournit lors de sa demande d’initiation une ou deux URL de call back :
La première (successfulReportUrl) sera appelée par l’établissement bancaire dans le cas où la demande d’initiation est traitée et si le PSU a donné son consentement pour le paiement. Un paramètre code est ajouté à la successfulReportUrl.
Exemple : https://<votre SuccessfulReportUrl>?code=GbmTn1ZZ76bibgvCRLxD4lNp8wMzkd
Cette information est importante car nécessaire pour obtenir le token d’accès à la méthode o-confirmation.
La seconde URL (unsuccessfulReportUrl) sera utilisée par l’établissement bancaire en cas de refus du consentement ou si la cinématique de validation de l’initiation de paiement est interrompue à une de ses étapes (exemple : timeout sur l’écran d’identification, sur l’écran de sélection du compte à débiter ou sur les écrans d’authentification forte). Cette seconde URL est facultative : la première URL call back (successfulReportUrl) sera utilisée si la seconde n’est pas renseignée, mais sans ajout de paramètre « code ».
3ème étape alternative : La redirection vers les écrans pour que le PSU valide le paiement en cas de parcours fluides
Cinématique nominale des enchaînements des écrans d’identification et d’authentification forte
Par défaut, il est demandé au PSU de s’authentifier fortement à deux reprises pour déclencher une demande de paiement. Il est possible de déclencher deux parcours fluides lorsque la requête contient des informations plus précises sur le compte débiteur :
- Parcours Fluide Bis : le debtorAccount est renseigné dans la demande d’initation de paiement
- Parcours Fluide : le debtorAccount et le privateId (*) sont renseignés dans la demande d’initation de paiement
| Parcours Fluide Bis | Parcours Fluide |
 |
 |
(*) Pour les Caisses d’Epargne, Banque BCP, Crédit Coopératif et BTP Banque et pour les segments de clientèles PRO et ENT : il s’agit du numéro d’abonné séparé du numéro d’usager par un tiret « -« .
Le déclenchement du parcours fluide Bis redirige le PSU vers l’écran de saisie de l’identifiant, c’est le même que dans le parcours classique. L’enchainement qui suit est le même peu importe le type de parcours fluide.
1 ) Le PSU est redirigé vers un écran récapitulatif de l’opération, il peut la valider ou l’annuler
Exemple de restitution pour le persona « Marc » des Banques Populaires qui dispose de 4 comptes dont le compte numéro 30019654051, (voir la rubrique « Comment tester l’API ? » > « Testez nos personas » pour les jeux de données de l’établissement) :
2) Le PSU est redirigé vers un premier écran d’authentification forte proposé par son établissement bancaire pour valider son identité.
Le code SMS pour authentification est à saisir ((voir la rubrique « Comment tester l’API ? » > « Testez nos personas« pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires:
La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du PSU par l’établissement bancaire (mot de passe + SMS OTP, secur’pass, etc.).
Elle dépend aussi de l’équipement du PSU sur lequel tourne l’application du PISP utilisée par le PSU (PC ou mobile/smartphone/tablette).
Note : en environnement de sandbox, le code SMS à saisir est systématiquement : « 12345678 »
3 ) Le PSU est ensuite redirigé vers l’APP du PISP, avec la fourniture du paramètre « code »
4ème étape : Récupérer le statut d’une initiation de paiement
Cet appel GET /payment-requests/{paymentRequestResourceId} vous permet de récupérer l’ensemble des données de l’initiation de paiement enrichies du resourceId et des statuts de l’initiation et du paiement qu’elle contient. La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Récupérer le statut d’une initiation de paiement« . Les données sont accessibles pendant 35 jours.
Pour l’accès à l’assemblage sandbox, le point d’entrée est identique aux requêtes précédentes :
Requête :
Headers :
Authorization : Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Content-Type : application/json
Signature : keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_<empreinte-sha256>\« , algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\ »
X-Request-ID : MyXrequestId123
Remarques sur l’alimentation des champs :
Authorization : Bearer => access_token récupéré pour le tokenCredential.
x-request-id => doit être le même que pour la requête d’initiation de paiement
Le paymentRequestResourceId est récupéré en réponse à la requête d’initiation de paiement, lorsque l’initiation de paiement a été traité et que le PSU a donné son consentement pour le paiement.
Réponse :
{ « paymentRequest »: { « resourceId »: « 0000000a22-156688979900016807956016 », « paymentInformationId »: « azertyui 1630919339 », « creationDateTime »: « 2021-09-05T09:25:22.527+02:00 », « numberOfTransactions »: 1, « initiatingParty »: { « name »: « Pisp Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Reaumur », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 12FR5 », « schemeName »: « COID », « issuer »: « ACPR » } }, « paymentTypeInformation »: { « serviceLevel »: « SEPA », « categoryPurpose »: « DVPM » }, « debtor »: { « name »: « Customer Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Leclerc », « 94512 Charenton-le-Pont » ] } }, « debtorAccount »: { « iban »: « FR7613807000243021933556300 » }, « debtorAgent »: { « bicFi »: « CCBPFRPP512 », « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId » }, « name »: « Cpy Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue De Gaulle », « 85000 LRSY » ] } }, « beneficiary »: { « isTrusted »: false, « creditorAgent »: { « bicFi »: « CCBPFRPP512 », « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId! » }, « name »: « Creditor Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue de la primaube », « 12512 RODEZ » ] } }, « creditor »: { « name »: « Amazon SA », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 avenue Maupassant », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 852126790 », « schemeName »: « BANK », « issuer »: « FR » } }, « creditorAccount »: { « iban »: « FR7613825002000400000541718 » } }, « chargeBearer »: « SLEV », « paymentInformationStatus »: « ACCP », « requestedExecutionDate »: « 2021-09-06T14:10:10.109+01:00 », « creditTransferTransaction »: [ { « paymentId »: { « resourceId »: « 0000006537-163091934100113807153727 », « instructionId »: « instructionId 1630919339 », « endToEndId »: « endToEndId 1630919339 » }, « requestedExecutionDate »: « 2021-09-06T15:10:10.109+02:00 », « instructedAmount »: { « currency »: « EUR », « amount »: « 2.41 » }, « purpose »: « COMC », « regulatoryReportingCodes »: [], « remittanceInformation »: { « unstructured »: [ « remittanceInformation01 » ] } } ], « supplementaryData »: { « acceptedAuthenticationApproach »: [ « REDIRECT » ], « appliedAuthenticationApproach »: « REDIRECT », « scaHint »: « scaExemption », « successfulReportUrl »: « https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK-12345&code_challenge_method=S256&code_challenge=ABCD » } }, « _links »: { « request »: { « href »: « /stet/psd2/v1.4.2/payment-requests/00000000a22-156688979900016807956016 », « templated »: false }, « confirmation »: { « href »: « /stet/psd2/v1.4.2/payment-requests/00000000a22-156688979900016807956016/o-confirmation », « templated »: false } }
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Remarques sur l’alimentation des champs :
resourceId => reprend le paymentRequestResourceId
paymentInformationStatus => reprend le statut de l’initiation de paiement
transactionStatus => reprend le statut de l’opération resourceId
X-Request-ID: transmis en entrée
5ème étape : Confirmer une initiation de paiement (uniquement en production, PAS en sandbox)
Cet appel POST /payment-requests/{paymentRequestResourceId}/o-confirmation vous permet de confirmer une initiation paiement. La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Confirmer une initiation un paiement« .
La méthode POST /payment-requests/{paymentRequestResourceId}/confirmation n’est pas implémentée.
En préalable à la consommation du service o-confirmation, il est requis d’obtenir un jeton d’accès spécifique via la requête suivante :
Requête :
POST https://www.13807.live.api.89C3.com/stet/psd2/oauth/token
Dans les Headers :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
Dans le body :
grant_type : authorization_code
client_id : PSDFR-ACPR-12345
code : le code récupéré en paramètre de l’appel à la successfulReportUrl en fin d’étape 3
code_verifier : en fonction de vos éléments PKCE
redirect_uri: https://myAPP.fr/Home/OAuth2Callback
Remarques sur l’alimentation des champs :
<cdetab> => code établissement des deux banques disponibles dans cet environnement soit :
13807 (Banque Populaire Grand Ouest) ;
17515 (Caisse d’Epargne Ile de France).
client_id :
Si l’enregistrement du TPP a été réalisé au travers du processus de « GoLive » via notre portail BPCE API :
=> il s’agit du numéro d’agrément donné par votre autorité compétente (PSDXX-YYYYYYYY-ZZZZZZZZ)
OU
si l’enregistrement du TPP a été réalisé via l’API register, client_id retourné dans la réponse au POST /register :
=> il s’agit du client_id retourné dans la réponse au POST /register
redirect_uri : URL de redirection prédéclarée dans votre application consommatrice ET à communiquer à l’ASPSP :
- lors de l’étape GO Assemblage (resp. GO Live en production) si le TPP a été enregistré par la procédure actuelle ;
- via l’API Register si le TPP s’est enregistré par la procédure automatisée.
grant_type => non modifiable = « authorization_code »
Réponse :
{
« access_token » : « secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs »,
« token_type » : « Bearer »,
« expires_in » : « 3600 »,
« refresh_token« : « 1ji8KA9RJ5eXeJV1xKSDj1WDp8wwg3pRgDO2j0WhtbMsWz »,
« scope » : « pisp »,
« state« : « OK-12345 »
}
Remarques sur l’alimentation des champs :
access_token => second token à transmettre dans le header de la prochaine méthode près le Bearer XX.
expires_in => durée de validité du token en secondes.
refresh_token => à mémoriser : permet d’obtenir un nouveau jeton d’accès si le délai de validité du premier jeton est échu (durée de quelques minutes). Le rafraichissement de jeton se fait via le grant-type= refresh_token.
state => L’ASPSP redonne la valeur « state » qui était présente dans la requête initiale de demande d’initiation de paiement (Valeur à la main du TPP).
Une fois le jeton d’accès obtenu, il est possible d’appeler la requête de confirmation de l’initiation de paiement ci-dessous (champ « Authorization »).
Requête:
Headers :
Authorization : Bearer secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs
Content-Type : application/json
Signature : keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_<empreinte-sha256>\« , algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\ »
X-Request-ID : MyXrequestId123
Body :
{
}
Remarques sur l’alimentation des champs :
Authorization : Bearer => second access_token récupéré pour le tokenCredential
{paymentRequestResourceId} : c’est l’identifiant transmis par le service de paiement au moment de l’initiation et qui est utilisé pour le GET
Réponse :
{ « paymentRequest » : {
« resourceId » : « 0000000a22-156688979900016807956016 »,
« paymentInformationId » : « MyPmtInfld123 »,
« creationDateTime » : « 2021-09-05T09:25:22.527+02:00 »,
« numberOfTransactions » : 1,
« debtorAgent » : {
« bicFi » : « CCBPFRPP512 »,
« name » : « Cpy Name »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 rue De Gaulle »,
« 85000 LRSY »
]
}
},
« initiatingParty » : {
« name » : « Pisp Name »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 rue Reaumur »,
« 75512 PARIS »
]
},
« organisationId » : {
« identification » : « 12FR5 »,
« schemeName » : « COID »,
« issuer » : « ACPR »
}
},
« paymentTypeInformation » : {
« serviceLevel » : « SEPA »,
« categoryPurpose » : « DVPM »
},
« debtor » : {
« name » : « Customer Name »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 rue Leclerc »,
« 94512 Charenton-le-Pont »
]
},
« privateId » : {
« identification » : « D0999990I0 »,
« schemeName » : « BANK »,
« issuer » : « BICXYYTT512 »
}
},
« debtorAccount » : {
« iban » : « FR7613807000243021933556300 »
},
« beneficiary » : {
« creditorAgent » : {
« bicFi » : « CCBPFRPP512 »,
« name » : « Creditor Name »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 rue de la primaube »,
« 12512 RODEZ »
]
}
},
« creditor » : {
« name » : « Amazon SA »,
« postalAddress » : {
« country » : « FR »,
« addressLine » : [
« 512 avenue Maupassant »,
« 75512 PARIS »
]
},
« organisationId » : {
« identification » : « 852126790 »,
« schemeName » : « BANK »,
« issuer » : « FR »
}
},
« creditorAccount » : {
« iban » : « FR7613825002000400000541718 »
}
},
« purpose » : « COMC »,
« chargeBearer » : « SLEV »,
« paymentInformationStatus » : « PDNG »,
« statusReasonInformation » : null,
« fundsAvailability » : null,
« booking » : null,
« requestedExecutionDate » : « 2021-09-06T14:10:10.109+01:00 »,
« creditTransferTransaction » : [
{
« paymentId » : {
« resourceId » : « 0000000a22-146329369000016907660677 »,
« instructionId » : « instructionId 1630919339 »,
« endToEndId » : « endToEndId 1630919339 »
},
« instructedAmount » : {
« currency » : « EUR »,
« amount » : « 2.41 »
},
« remittanceInformation »: {
« unstructured »: [
« remittanceInformation01 »
]
},
« transactionStatus » : « PDNG »
}
],
« supplementaryData » : {
« appliedAuthenticationApproach » : « REDIRECT »,
« scaHint » : « scaExemption »,
« successfulReportUrl »: https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK- 12345&code_challenge_method=S256&code_challenge=T3LPv9JWu_HtyEQOkDCo4YYRmZJXTjJ0Ng9jfq_UBBg
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Remarques sur l’alimentation des champs :
paymentRequestResourceId => identifiant à passer à la requête POST/payment-requests pour confirmer l’initiation de paiement
appliedAuthenticationApproach » = « REDIRECT » => seule valeur autorisée
href => URL de la page de redirection vers les écrans d’identification et d’authentification de l’établissement
nonce => anti rejeu technique
6ème étape : Annuler une initiation de Paiement
Cet appel vous permet d’annuler une initiation paiement en demandant au PSU connecté de donner son consentement pour l’annulation. La description de la fonctionnalité et des champs de la requête est décrite dans le cas d’usage « Annuler une initiation un paiement« .
Rappel : la méthode d’authentification supportée par l’établissement bancaire est le mode REDIRECTsimple => les cinématiques de l’enchaînement de l’écran d’identification et d’authentification forte décrites ci-après correspondent à ce mode d’authentification.
Pour l’accès à l’assemblage sandbox, le point d’entrée est identique : www.<cdetab>.sandbox.api.89c3.com
Requête :
Headers :
Authorization : Bearer secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs
Content-Type : application/json
Signature : keyId=\ »https://<www.myUrlPath.to>/myQsealCertificate_<empreinte-sha256>\« , algorithm=\ »rsa-sha256\ », headers=\ »(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\ », signature=\ »LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\ »
X-Request-ID : MyXrequestId123
Body :
{ « resourceId »: « 0000000a22-156688979900016807956016 », « paymentInformationId »: « MyPmtInfld123 », « creationDateTime »: « 2021-09-05T09:25:22.527+02:00 », « numberOfTransactions »: 1, « initiatingParty »: { « name »: « Pisp Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Reaumur », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 12FR5 », « schemeName »: « COID », « issuer »: « ACPR » } }, « paymentTypeInformation »: { « serviceLevel »: « SEPA », « categoryPurpose »: « DVPM » }, « debtor »: { « name »: « Customer Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue Leclerc », « 94512 Charenton-le-Pont » ] } }, « debtorAccount »: { « iban »: « FR7613807000243021933556300 » }, « debtorAgent »: { « bicFi »: « CCBPFRPP512 », « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId » }, « name »: « Cpy Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue De Gaulle », « 85000 LRSY » ] } }, « beneficiary »: { « isTrusted »: false, « creditorAgent »: { « bicFi »: « CCBPFRPP512 », « clearingSystemMemberId »: { « clearingSystemId »: « clearingSystemId », « memberId »: « memberId! » }, « name »: « Creditor Name », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 rue de la primaube », « 12512 RODEZ » ] } }, « creditor »: { « name »: « Amazon SA », « postalAddress »: { « country »: « FR », « addressLine »: [ « 512 avenue Maupassant », « 75512 PARIS » ] }, « organisationId »: { « identification »: « 852126790 », « schemeName »: « BANK », « issuer »: « FR » } }, « creditorAccount »: { « iban »: « FR7613825002000400000541718 » } }, « chargeBearer »: « SLEV », « paymentInformationStatus »: « ACCP », « requestedExecutionDate »: « 22021-09-06T14:10:10.109+01:00 », « creditTransferTransaction »: [ { « paymentId »: { « resourceId »: « 0000000a22-156688979900016807956016 », « instructionId »: « instructionId 1630919339 », « endToEndId »: « endToEndId 1630919339 » }, « requestedExecutionDate »: « 2021-09-06T14:10:10.109+01:00 », « instructedAmount »: { « currency »: « EUR », « amount »: « 2.41 » }, « purpose »: « COMC », « regulatoryReportingCodes »: [], « remittanceInformation »: { « unstructured »: [ « remittanceInformation01 » ] }, « transactionStatus »: « RJCT », « statusReasonInformation »: “DS02” } ], « supplementaryData »: { « acceptedAuthenticationApproach »: [ « REDIRECT », « DECOUPLED » ], « appliedAuthenticationApproach »: « REDIRECT », « scaHint »: « scaExemption », « successfulReportUrl »: « https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK-12345&code_challenge_method=S256&code_challenge=T3LPv9JWu_HtyEQOkDCo4YYRmZJXTjJ0Ng9jfq_UBBg » }}
Remarques sur l’alimentation des champs :
Authorization : Bearer => second access_token récupéré
{paymentRequestResourceId} : c’est l’identifiant transmis par le service de paiement au moment de l’initiation et qui est utilisé pour le GET
Les données du body doivent être identiques à celles récupérées au moment du GET, à part les suivantes au niveau de la transaction à annuler :
– le transactionStatus de l’objet creditTransferTransaction qui doit être passé à « RJCT »
– le statusReasonInformation de l’objet creditTransferTransaction à « DS02 »
– la partie _links doit être supprimée
– l’enveloppe objet du parent « paymentRequest » : {doit être supprimé, ainsi que l’accolade fermante associée en fin de flux.
Réponse :
{ « appliedAuthenticationApproach »: « REDIRECT », « _links »: { « consentApproval »: { « href »: « https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v1.4.2/cancellation?paymentRequestResourceId=0000000a22-156688979900016807956016&nonce=Ij4VifKlm4QICq12345 », « templated »: true } }}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Remarques sur l’alimentation des champs :
paymentRequestResourceId => identifiant à passer à la requête GET /payment-requests pour récupérer le statut de l’initiation de paiement
appliedAuthenticationApproach » = « REDIRECT » => seule valeur autorisée
href => URL de la page de redirection vers les écrans d’identification et d’authentification de l’établissement
nonce => anti rejeu technique
currency => récupérée du body passé en entrée
successfulReportUrl => récupérée du body passé en entrée
unsuccessfulReportUrl => récupérée du body passé en entrée
creditorAccount => récupérée du body passé en entrée
creditorName => récupérée du body passé en entrée
amount => récupérée du body passé en entrée
successfulReportUrl => récupérée du body passé en entrée
debtorAccount => récupérée du body passé en entrée
debtorName => récupérée du body passé en entrée
privateId => récupérée du body passé en entrée
requestedExecutionDate=> récupérée du body passé en entrée
method => UFVU est égal à PUT en base64 + URL
X-Request-ID: transmis en entrée
7ème étape : La redirection vers les écrans pour que le client valide l’annulation d’une initiation de paiement
Cinématique nominale des enchaînements des écrans d’identification et d’authentification forte
Déroulé de l’enchaînement des écrans d’identification et d’authentification forte :
A partir de l’URI retournée dans consentApproval il est possible de jouer l’enchaînement des écrans.
1) Le PSU est redirigé vers un écran d’identification proposé par son établissement bancaire et dans lequel il saisira son identifiant de banque à distance.
Attention : l’appel à cet écran ne peut être effectué qu’une seule fois
=> le nonce transmis dans l’URL permettant d’accéder à cet écran n’est utilisable qu’une seule fois (il est grillé en suite par l’anti-rejeu)
=> une nouvelle demande d’annulation de virement DSP2 (via PUT PaymentRequest ) est nécessaire pour récupérer un nouveau jeton nonce si nécessaire.
L’identifiant de banque à distance du PSU est à saisir (voir la rubrique « Comment tester l’API ? » > « Testez nos personas » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires :
Remarque : Le bouton « Mémoriser mon identifiant » n’est pas opérationnel. L’activer ne sert à rien.
Pour les Caisses d’Epargne, si le PSU est un professionnel ou une entreprise, il devra saisir son numéro d’usager en plus de son identifiant de banque à distance :
2) Le PSU est redirigé vers un écran d’authentification forte proposé par son établissement bancaire pour valider son identité.
Le code SMS pour authentification est à saisir (voir la rubrique « Comment tester l’API ? » > « Testez nos personas » pour les jeux de données de l’établissement), exemple pour le persona « Marc » des Banques Populaires:
La cinématique de cette étape dépend de la méthode d’authentification forte mise à disposition du PSU par l’établissement bancaire (SMS OTP, secur’pass, etc.).
Elle dépend aussi de l’équipement du PSU sur lequel tourne l’APP du PISP utilisée par le PSU (PC ou mobile/smartphone/tablette).
Remarque : en environnement sandbox, le code SMS est systématiquement « 12345678 ».
3) Le PSU est redirigé vers un écran récapitulatif de l’opération en cours d’annulation proposé par son établissement bancaire.
Exemple de restitution pour le persona « Marc » des Banques Populaires veut annuler sa transaction de 2,12 euros émise depuis son Compte Perso. Il peut annuler ou valider son opération d’annulation.
4) Le PSU valide l’annulation du virement.
5) Le PSU est redirigé vers un écran de confirmation de l’opération proposé par son établissement bancaire.
NB : lorsque le PSU ne confirme pas l’annulation de paiement (ou en cas de timeout sur la page récapitulative de l’opération par exemple) le PSU est redirigé vers la page suivante,
6) Le PSU est redirigé vers l’application du TPP PISP.
Le PISP fournit lors de sa demande d’annulation une ou deux URL de call back :
La première (successfulReportUrl) sera appelée par l’établissement bancaire dans le cas où la demande d’annulation est traitée et si le PSU a donné son consentement pour cette annulation d’opération.
La seconde URL (unsuccessfulReportUrl) sera utilisée par l’établissement bancaire en cas de refus du consentement ou si la cinématique de validation de l’annulation de paiement est interrompue à une de ses étapes (exemple : timeout sur l’écran d’identification, sur l’écran récapitulatif de l’opération ou sur les écrans d’authentification forte). Cette seconde URL est facultative : la première URL call back (successfulReportUrl) sera utilisée si la seconde n’est pas renseignée.
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.
Nos personas
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.
Il est aussi demandé l’utilisation de données fictives. C’est l’objectif de ces données de tests sous forme de « persona » qui rassemblent divers clients sur base de :
- segment de clientèle (étudiant, actif, retraité, entrepreneur individuel, etc..) ;
- caractéristiques de leurs comptes (mono-compte, multi-comptes, solde qui est statique) ;
- le consentement PSU a déjà été donné ;
- données utiles attendues en entrée par les API (identifiant banque à distance, IBAN).
Ce jeu de données évoluera au cours du temps avec rajout de données additionnelles (autres clients, nombre de transactions, profondeur d’historique). Revenez régulièrement sur cette section pour être à jour !
LES IDENTIFIANTS ET DONNEES DE TEST CI-DESSOUS NE PEUVENT PAS ETRE UTILISEES EN PRODUCTION LIVE.
Persona
- Actif Entrepreneur Individuel
- 4 comptes (abonné PART) dont 2 liés à son activité professionnelle
NOUVEAU !
- 2000 transactions disponibles sur l’IBAN FR7612579007000860000716515
- 2000 transactions disponibles sur l’IBAN FR7612759007000800099862143
- 260 transactions disponibles sur l’IBAN FR7612759007000800081593745
- 200 transactions disponibles sur l’IBAN FR7612759007000800060486060
avec une variété importante des types d’opérations :
- SDD émis à crédit du compte
- SDD reçus à débit du compte
- Paiements par carte à débit du compte
- Remises commerçant à crédit du compte
- Virements émis à débit du compte
- Virements reçus à crédit du compte
- Frais divers
- Echéances de prêt
- Chèques tirés à débit du compte
- Chèques déposés à crédit du compte
NB : pour ce persona, il vous faudra saisir le code SMS = « 12345678 » dans l’écran d’authentification proposé en mode assemblage.
| Persona | Segmentbanque | Nouvel Identifiant | Code établissement | IBAN | Détenteur | Consentement :Solde/Transactions/Identité | Solde | Devise |
| EDMÉ | Entrepreneurindividuel | 9999999801 | 12579 | FR7612579007000860000716515 | MR EDMÉ D’EIDASE | OUI/OUI/NON | +470 926.57 | EUR |
| FR7612759007000800099862143 | MR EDMÉ D’EIDASE | OUI/OUI/NON | +182 432.23 | EUR | ||||
| FR7612759007000800081593745 | MR EDMÉ D’EIDASE | OUI/OUI/NON | +9 803.71 | EUR | ||||
| FR7612759007000800060486060 | MR EDMÉ D’EIDASE | OUI/OUI/NON | +14 646.78 | EUR |
Historique des versions
Version de la norme STET utilisée pour l’API
Cette API REST est conforme à la spécification interbancaire française STET (https://www.stet.eu/en/psd2/), version v.1.4.2.17, afin de répondre aux exigences règlementaires de la DSP2. Elle tient compte des limitations fonctionnelles aux Banques BCP décrites dans la section « Limitations ». Elle tient compte des limitations fonctionnelles propres aux Banques BCP.
Pour rappel :
- les textes de la directive de paiement numéro 2 (DSP2, référence UE 2015/2366 du 25/11/2015) sont rentrés en application le 13 janvier 2018 : http://eur-lex.europa.eu/legal-content/FR/TXT/?uri=CELEX:32015L2366
- ils ont été complétés par les normes techniques de réglementation (NTR, règlement délégué UE 2018/389) relatives à l’authentification forte du client et à des normes ouvertes communes et sécurisées de communication dont la date d’application se situe au 14 septembre 2019. Ces normes sont les RTS (Rules Technical Standards) : https://eur-lex.europa.eu/legal-content/FR/TXT/?toc=OJ%3AL%3A2018%3A069%3ATOC&uri=uriserv%3AOJ.L_.2018.069.01.0023.01.FRA
En France, l’ordonnance n° 2017-1252 du 9 août 2017 transpose la directive DSP2 dans la partie législative du code monétaire et financier. L’ordonnance est complétée au plan réglementaire par les décrets n° 2017-1313 et n° 2017-1314 du 31 août 2017 et les cinq arrêtés du 31 août 2017.
Les utilisateurs peuvent également consulter l’assistant virtuel en cliquant sur le pictogramme sur la page d’accueil du portail.
Description du support
Conformément à l’article 30 (5) des RTS, une assistance pour les prestataires PSP tiers est mise à disposition. Ce support est accessible via le formulaire sur ce portail BPCE API, ou via https://www.api.89c3.com/fr/nous-contacter. Les réponses se font pendant les heures de travail ouvrées.
Le principe général du support est schématisé ci-dessous en prenant en compte les délais réglementaires prévus à l’article 30 (4) des RTS :
Versionning de l’API
| Nos versions API | Version norme STET |
| v1.4.2 | v1.4.2.17 |
Vous pouvez consulter l’assistant virtuel au sujet des textes de la norme STET.
Evolutions importantes apportées depuis la première version livrée
| Cas d’usage / Méthode(s) | Date d’effet | Description de l’évolution |
| POST /payment-requests GET /payment-requests/{paymentRequestResourceId} | 17 mai 2019 | Documentation portail :
|
| Toutes | 31 juillet 2019 | Documentation portail :
|
| Roadmap | 18 septembre 2019 | Documentation portail :
|
| Eligibilité | 1er octobre 2019 | Documentation portail :
|
| Initier un paiement | 19 novembre 2019 | Documentation portail:
|
| Comment utiliser le fallback | 21 novembre 2019 | Documentation portail :
|
| Récupérer le statut d’une initiation de paiement | 9 décembre 2019 | Documentation portail :
|
| Tester nos persona | 23 décembre 2019 | Documentation portail :
|
| Initier un paiement | 24 décembre 2019 | Activation de la prise en compte de l’IBAN transmis dans le champ debtorAccount => IBAN du PSU : lorsqu’il est renseigné, le seul compte sélectionnable pour le PSU est celui qui correspond à cet IBAN. |
| Historique des versions / roadmap | 30 décembre 2019 | Documentation portail :
|
| Limitations / Historique des versions / roadmap | 25 février 2020 | Activation de l’API pour les autres BP que BPGO.
Modification du versionning de l’API. |
| Annuler une initiation de paiement / sandbox / limitations | 10 septembre 2020 | Activation de la méthode d’annulation d’une initiation de paiement. |
| POST /payment-requests | 2 décembre 2020 | Documentation portail :
|
| Initier un paiement / Récupérer le statut d’une initiation de paiement / Sandbox / Roadmap | 22 décembre 2020 | Depuis le 7 décembre :
|
| Toutes | 4 janvier 2021 | Documentation portail :
|
| Toutes | 30 juin 2021 | Mise à jour de la documentation en fonction des derniers éléments livrés pour la trajectoire réglementaire
|
| Initiation de paiement
Roadmap |
13 octobre 2021 | Activation du SCT Core pour le segment ENT
Précision sur les changements sans délai non soumises au préavis réglementaire |
| Initiation de paiement | 03 janvier 2022 | Précisions sur le pkce + BIC Creditor devenu optionnel pour les opérations PIS effectuées en zone SEPA + nouveau moyen SCA = certificat TurboSign |
| Cas d’usage PIS et Limitations | 01 avril 2022 | Précisions sur le délai max d’inactivité du PSU, les abonnés professionnels, et les demandes PIS ayant les mêmes caractéristiques, montants min/max, limitation sur creditor.name et précision sur le keyID |
Roadmap
Politique de décommissionnement des versions de l’API
La politique du décommissionnement (= arrêt d’une version d’une API sur les environnements de production et sandbox) est fonction du cycle de vie des API, et il est prévu une phase de tuilage entre deux versions majeures d’API comme indiqué dans le schéma ci-dessous :
La communication du décommissionnement d’une version N se fera à la date de déploiement de la version N+1. Le canal de communication privilégié est le portail BPCE API dans la partie « Roadmap » de l’API impactée. Une communication via courriel vers les correspondants des prestataires enrôlés sur le portail BPCE API pourra venir compléter ce dispositif.
Planning des évolutions fonctionnelles à venir de l’API
L’API d’Information sur compte fait l’objet d’améliorations et d’évolutions*.
(*) NB : l’article 30 (4) des RTS précise que des changements significatifs de l’API peuvent intervenir sans délai. Nous appliquons cette clause dans les cas suivants :
- problème bloquant impactant de façon généralisée au moins l’un des segments de clients majeur (particuliers, professionnels, entreprises),
- problème de sécurité,
- évolutions demandées par les autorités nationales compétentes pour répondre à la trajectoire réglementaire.
Retrouvez ci-dessous notre roadmap prévisionnelle.
| Version de l’API | Version de la norme STET | Fonctionnalités | Sandbox
Date de déploiement BPCE API Dev Portal & Sandbox |
Live
Date de déploiement BPCE Live API Gateway |
Date de décommissionnement |
| v1.4.2 | v1.4.2.17 |
|
24 septembre 2020 | 30 juin 2021 | non encore annoncée |
| v1.4.2 | v1.4.2.17 | Fonctionalités rajoutées en gras ci-dessous :
|
30 mars 2021 | 30 juin 2021 | non encore annoncée |
