Assemblage sandbox

➤ Introduction - précisions sur les fonctionnalités de la sandbox

La sandbox 89C3 API peut être utilisée de 2 manières :

  • Via le Try-it du portail 89c3-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 89C3 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 :

  • Les cas d’usage "Confirmer une initiation de paiement" et "Annuler une initiation de paiement", ne sont pas totalement testables dans l’environnement sandbox car ces méthodes nécessitent un croisement des données dynamiques alors que notre sandbox a un comportement statique :
    • Les requêtes o-confirmation ne sont pas du tout supportées;
    • 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" (non disponible en sandbox) 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 "paymentRequestRessourceId" récupéré du résultat de la première requête

  • Puis, en exécutant la requête de confirmation du paiement "POST /payment-requests/{paymentRequestResourceId}/o-confirmation" en passant en paramètre le "paymentRequestRessourceId" récupéré du résultat de la première requête (non disponible en sandbox)

  • Puis, en exécutant la requête d'annulation du paiement "PUT /payment-requests/{payementRequestResourceId}en passant en paramètre le "paymentRequestRessourceId" et le body modifié récupéré du résultat de la seconde requête

Les données utilisées pour faire les tests seront issues des personas (voir la rubrique "Comment tester l'API ?" > "Testez nos persona"), ce qui permettra de choisir des profils spécifiques selon les tests de façon à mieux appréhender les résultats obtenus.

 

➤ Prérequis

Vous devez déclarer votre APP sur le portail 89C3 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é (ou en cours d'accréditation) 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 établissementNom de l'établissementNom 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 89C3 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" : "nACXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz",

"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 REDIRECT renforcé => 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 nACXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz

Headers :

Content-Type : application/json

Signature : keyId=\"MZGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB\",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",
            "DECOUPLED"
        ],
        "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 => access_token récupéré pour le tokenCredential

Les données suivantes devant être unique, sans quoi la requête est rejetée pour cause de doublon (le rejeu n'est pas autorisé) :

paymentInformationId ;

- instructionId ;

endToEndId ;

- x-request-id.

debtor/privateId/identification => identifiant d'accès à la banque à distance pour le PSU : lorsqu'il est renseigné et que debtorAccount est renseigné, l'appel à l'écran d'identification du PSU n'est pas effectué.

debtorAccount => IBAN du PSU : lorsqu'il est renseigné, le seul compte sélectionnable pour le PSU est celui qui correspond à cet IBAN, pour peu que le compte soit éligible aux virements PISP. 

Les fonctionnalités mises en œuvre peuvent différer entre les Banques Populaires et les Caisses d'Epargne (cf. cas d'usage "Initier un paiement").

Réponse :

{

"appliedAuthenticationApproach" : "REDIRECT",

"_links" : {

"consentApproval" : {

"href" :"https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v2/identificationPisp?paymentRequestRessourceId=000000b66f-163091517400013807415858&nonce=qJammuGI0OGCwznaZ0YO&creditorName=QW1hem9uIFNB&creditorAccount=RlI3NjEzODI1MDAyMDAwNDAwMDAwMDQxNzE3&amount=Mi40MQ%3D%3D&currency=RVVS&successfulReportUrl=aHR0cHM6Ly9leHRlbnNpb25zLmJwY2UuZnIvT0F1dGgyQ2FsbGJhY2suYXNweCZzdGF0ZT1PSy0xMjM0NSZjb2RlX2NoYWxsZW5nZV9tZXRob2Q9UzI1NiZjb2RlX2NoYWxsZW5nZT1UM0xQdjlKV3VfSHR5RVFPa0RDbzRZWVJtWkpYVGpKME5nOWpmcV9VQkJn&requestedExecutionDate=MjAyMS0wOS0wNlQxNToxMDoxMC4xMDkrMDI6MDA%3D&method=UE9TVA%3D%3D&categoryPurpose=RFZQTQ%3D%3D”, 

"templated" : true

}

}

}

Headers :

X-Request-ID : MyXrequestId123

Status code : 201 OK

Remarques sur l'alimentation des champs :

paymentRequestRessourceId => identifiant à passer à la requête GET /payment-requests pour récupérer le statut de l'initiation de paiement

appliedAuthenticationApproach" = "REDIRECT" => seule valeur autorisée

href => URL de la page de redirection vers les écrans d'identification et d'authentification de l'établissement

nonce => anti rejeu technique

currency => récupérée du body passé en entrée

successfulReportUrl => récupérée du body passé en entrée

unsuccessfulReportUrl => récupérée du body passé en entrée

iban => récupérée du body passé en entrée

creditorName => récupérée du body passé en entrée

X-Request-ID: transmis en entrée

  

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

Cinématique PISP v1.4.2 20210909

 

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.

sandbox 01

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 :

sandbox 02

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.

 sandbox 03

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

PISP 4 1 MireAuthenteBP bis

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:

 

PISP 4 1 MireAuthenteBP penta

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

PISP 5 1 AccountSelect

 

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

PISP 5 1 AccountSelect bis

 

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.

PISP X ErreurEligibilite

 

 

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

PISP 5 2 AccountSelect

 

 

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<strong< a="">>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
 Cinématique PISP fluide bis 20210909  Cinématique PISP fluide 20210909

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

recap fluide

 

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

PISP 4 1 MireAuthenteBP bis

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:

PISP 4 1 MireAuthenteBP penta

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 ressourceId 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 nACXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz

Content-Type : application/json

Signature : keyId=\"https://www.mykeyid.com/keyfile\",algorithm=\"rsa-sha256\",headers=\"(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\",signature=\"LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\

X-Request-ID : MyXrequestId123

Remarques sur l'alimentation des champs :

Authorization : Bearer => access_token récupéré pour le tokenCredential.

x-request-id => doit être le même que pour la requête d'initiation de paiement

Le paymentRequestRessourceId est récupéré en réponse à la requête d'initiation de paiement, lorsque l'initiation de paiement a été traité et que le PSU a donné son consentement pour le paiement.

Réponse :

{
    "paymentRequest": {
        "resourceId": "0000000a22-156688979900016807956016",
        "paymentInformationId": "azertyui 1630919339",
        "creationDateTime": "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",
                "DECOUPLED"
            ],
            "appliedAuthenticationApproach": "REDIRECT",
            "scaHint": "scaExemption",
        }
    },
    "_links": {
        "request": {
            "href": "/stet/psd2/v1.4.2/payment-requests/0000006537-163091934100013807111620",
            "templated": false
        },
        "confirmation": {
            "href": "/stet/psd2/v1.4.2/payment-requests/0000006537-163091934100013807111620/o-confirmation",
            "templated": false
        }
    }

Headers :

X-Request-ID : MyXrequestId123

 Status code : 200 OK

Remarques sur l'alimentation des champs :

resourceId => reprend le paymentRequestRessourceId

paymentInformationStatus => reprend le statut de l'initiation de paiement

transactionStatus => reprend le statut de l'opération resourceId

X-Request-ID: transmis en entrée

 

5ème étape : Confirmer une initiation de paiement (uniquement en live prod)

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.

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 successfulURL 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 89C3 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

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 ;
  • à 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" : "nACXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz",

"token_type" : "Bearer",

"expires_in" : "3600",

"refresh_token": "1ji8KA9RJ5eXeJV1xKSDj1WDp8wwg3pRgDO2j0WhtbMsWz",

"scope" : "pisp",

"state": "OK-12345"

}

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.

refresh_token => A 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.

Requête (en prod live):

POST https://www.13807.live.api.89C3.com/stet/psd2/v1.4.2/payment-requests/0000000a22-156688979900016807956016/o-confirmation

Headers :

Authorization : Bearer nACXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz

Content-Type : application/json

Signature : keyId=\"https://www.mykeyid.com/mykeyfile\",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 => 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://www.api.89c3.com",

      "unsuccessfulReportUrl" : "https://www.api.89c3.com"

    }

  }

}


Headers :

X-Request-ID : MyXrequestId123

Status code : 200 OK 

Remarques sur l'alimentation des champs :

paymentRequestRessourceId => identifiant à passer à la requête POST/payment-requests pour confirmer l'initiation de paiement

appliedAuthenticationApproach" = "REDIRECT" => seule valeur autorisée

href => URL de la page de redirection vers les écrans d'identification et d'authentification de l'établissement

nonce => anti rejeu technique

 

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 REDIRECT simple => 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 nACXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz

Content-Type : application/json

Signature : keyId=\"https://www.mykeyid.com/mykeyfile\",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",
        }
}

Remarques sur l'alimentation des champs :

Authorization : Bearer => 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

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?paymentRequestRessourceId=0000000a22-156688979900016807956016&nonce=Ij4VifKlm4QICqEdSCke&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
        }
    }
}

 

Headers : 

X-Request-ID : MyXrequestId123

Status code : 200 OK 

Remarques sur l'alimentation des champs :  

paymentRequestRessourceId => identifiant à passer à la requête GET /payment-requests pour récupérer le statut de l'initiation de paiement 

appliedAuthenticationApproach" = "REDIRECT" => seule valeur autorisée 

href => URL de la page de redirection vers les écrans d'identification et d'authentification de l'établissement 

nonce => anti rejeu technique 

currency => récupérée du body passé en entrée 

successfulReportUrl => récupérée du body passé en entrée 

unsuccessfulReportUrl => récupérée du body passé en entrée 

creditorAccount => récupérée du body passé en entrée 

creditorName => récupérée du body passé en entrée 

amount => récupérée du body passé en entrée 

successfulReportUrl => récupérée du body passé en entrée 

debtorAccount => récupérée du body passé en entrée 

debtorName => récupérée du body passé en entrée 

privateId => récupérée du body passé en entrée 

requestedExecutionDate=> récupérée du body passé en entrée 

method => UFVU est égal à PUT en base64 + URL 

X-Request-ID: transmis en entrée

 

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

 sandbox 04

 

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.

sandbox 05

 

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 :

sandbox 06

 

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 :

sandbox 07

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

PISP 4 1 MireAuthenteBP bis

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:

PISP 4 1 MireAuthenteBP penta

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.

sandbox 08

 

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.

sandbox 09

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, 

sandbox 10

 

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.