Assemblage sandbox

➤ Introduction

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

  • soit via le Try-it du portail 89c3-API (se référer à la rubrique "Comment tester l'API ?" > "Console Try-it")

  • soit directement via votre application : c'est le mode assemblage décrit ci-après

Les données utilisées sont fictives (voir la rubrique "Comment tester l'API ?" > "Tester nos personas").

Elles permettront de choisir des profils spécifiques de façon à mieux cibler vos tests.

 

 

➤ Prérequis

Vous devez déclarer votre APP sur le portail 89C3 API (menu "Mes applications") et nous transmettre : 

  • votre identifiant fourni par votre autorité compétente (Organization Identifier = OID)
  • les clés publiques de vos certificats QWAC et QSEALC (jeu de certificats de production dédié aux tests)
  • votre uri de redirection (redirect_uri) qui sera appelée par l'ASPSP :
    • si le PSU a autorisé la récupération de ses données par l'AISP
    • ou en cas de refus du consentement
    • ou si la cinématique ci-dessous est interrompue (par exemple : timeout sur les écrans)

Rappel : vous devez être accrédité pour le rôle "AISP". 

 

 

➤ Enchaînement des étapes

 

1ère étape : demande de jeton d'accès

Ceci est nécessaire afin d’obtenir un jeton d’accès à toutes fins de consommer les ressources de l’API, et permet de déclencher la redirection du PSU chez l'ASPSP.

La description de la fonctionnalité est décrite dans la rubrique "Vue d'ensemble" > "Récupérer votre jeton".

NB : Le PSU peut domicilier ses comptes dans plusieurs banques du Groupe BPCE. Il vous faudra un jeton différent pour accéder à chacune de ces banques --> cet appel est donc à répéter pour chacun des établissements concernés.

Notre point d’entrée dépend du code établissement : www.<cdetab>.sandbox.api.89C3.com , et pour l’assemblage sandbox, le <cdetab> de la Banque BCP est 12579.

   

Exemple de requête en assemblage sandbox :

GET https://www.12579.sandbox.api.89C3.com/stet/psd2/oauth/authorize

   

Headers :

Content-Type:application/x-www-form-urlencoded; charset=utf-8

Params:

response_type:code

client_id:PSDFR-ACPR-13807

redirect_uri:https://myAPP.fr/Home/OAuth2Callback

scope:aisp

Remarque sur l'alimentation des champs :

  • client_id: identifiant fourni par votre autorité nationale compétente (PSDXX-YYYY-ZZZZZ)
  • redirect_uri: URL de redirection prédéclarée dans votre application consommatrice ET à communiquer à l'ASPSP pour toute une demande d'assemblage ou de Go Live 

 

2ème étape : redirection vers les écrans d'authentification forte (AF/SCA)

Une fois redirigé vers l'ASPSP, celui-ci va afficher des écrans d'identification et d'authentification au PSU. 

La cinématique nominale des enchaînements de ces écrans est résumée par le schéma ci-dessous :

cinématique globale AISP

   

 

 

 

 

 

 

 

 

 

 

 

  

 

  

1. Le PSU est redirigé vers un écran d'identification proposé par ASPSP.

L'identifiant banque à distance du PSU est à saisir :

sandbox ecran mob ID saisi4

 

 

 

 

 

 

 

 

 

 

 

NB : si le PSU est un professionnel ou une entreprise, il y aura un numéro d'usager à saisir en sus de l'identifiant banque à distance.

 

2. Le PSU se voit afficher alors un écran d'authentification forte (AF/SCA) proposé par l'ASPSP pour valider son identité.

La cinématique dépend aussi de la méthode AF/SCA mise à disposition par l'ASPSP (exemple d'un OTP par SMS, voir exemple ci-dessous): 

 

 

sandbox ecran mob SCA saisi2    ou pour la sandbox   ecran SMS sandbox

 

NB : Dans certains cas, une notification peut être envoyée vers le PSU afin qu'il active son moyen d'AF/SCA sur son smartphone pour terminer cette étape :

Capture SCA OK3

 

 

 

 

 

 

 

 

 

 

 

 

3ème étape : récupération du jeton d'accès / access_token

Cet appel permet à l'AISP de récupérer le jeton d’accès pour pouvoir accéder aux données. Auparavant, il faudra que l'AISP demande au PSU connecté à quelles données il peut accéder.

La description de la fonctionnalité est décrite dans la rubrique "Vue d'ensemble" > "Récupérez votre jeton".

 

Le certificat QWAC est à fournir dans cette requête POST /stet/psd2/oauth/token pour établir l'authentification mutuelle avec l'ASPSP. Le certificat doit correspondre à celui-ci que le PSP a fourni:

  • lors de l’étape goAssemblage (resp. goLive en production) si le TPP a été enregistré par la procédure via le portail 89C3 API

  

Si le client vous a autorisé à récupérer ses données pour un établissement, vous trouverez dans la réponse à l’appel précédent, le code à utilisation unique qui permet de récupérer un access_token

Cet access_token est valable 1h et est un prérequis pour chaque accès à l'une des méthodes de l'API d'information sur compte. La description de la fonctionnalité et des champs de la requête est décrite dans le cas d'usage "Récupérer votre jeton".

Ce jeton est accompagné d’un refresh_token valable 90 jours que vous devez conserver. Lorsque votre access_token arrive à expiration, vous pouvez en redemander un nouveau en suivant la cinématique "Rafraîchir votre acces_token" ci-après. 

Au bout de 90 jours votre refresh_token arrive à expiration. Pour en récupérer un nouveau, vous devez reprendre la cinématique "Récupérer un jeton d'accès " et passer par une nouvelle étape d’authentification forte du client auprès de l'établissement bancaire. 

 

Exemple de requête en assemblage sandbox :

POST https://www.12579.sandbox.api.89C3.com/stet/psd2/oauth/token

Header:

Content-Type:application/x-www-form-urlencoded; charset=utf-8

Params:

client_id:PSDFR-ACPR-13807

grant_type:authorization_code

code:NnZx1hqHY2CLkCFjiTwhJeflgFedCBa

redirect_uri:https://myAPP.fr/Home/OAuth2Callback

 

Remarques sur l'alimentation des champs :

  • client_id : numéro donné par votre autorité compétente lors de votre demande d’agrément (PSDXX-YYYY-ZZZZZ)
  • code : récupéré dans l’url de callback
  • redirect_uri : il faut que cette "redirect_uri" soit identique à celle envoyée dans la requête GET /authorize !!!
  • le certificat eiDAS QWAC doit être envoyé avec cette requête.

 

Réponse :

{
   "access_token":"KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAs6iLw",
   "token_type":"Bearer",
   "expires_in":3600,
   "scope":"aisp offline_access",
   "refresh_token":"KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAs6iLa"
}



 

4ème étape : consommation des méthodes de l'API  

1) Obtenir la liste des comptes à vue d'un PSU

Une fois le jeton d'accès récupéré après l'authentification forte du PSU, cet appel vous permet de lister les comptes du PSU connecté lors de la première connexion.

La description de la fonctionnalité est décrite dans le cas d'usage "Obtenir la liste des comptes", notamment sur la pemière utilisation de cette méthode avant un PUT /consents.

La séquence est :

  1. GET /accounts pour récupérer les comptes sans les links vers les soldes et transactions
  2. affichage des comptes au client par le TPP pour récupérer son consentement
  3. PUT /consents pour transmettre le consentement sur les comptes
  4. GET /accounts pour récupérer les comptes consentis avec les links vers le solde (si donnée consentie) et/ou vers les transactions (si données consenties)

 

Exemple de requête en assemblage sandbox SANS la méthode PUT /Consent au préalable:

GET https://www.12579.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts

Header :

Authorization:Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-Request-ID:id-1234567890111121 1 

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+C2lVBNJrViMJBezFK7AYVjnSWH7t1QiMViAmthebEst=\

Psu-IP-Address:192.168.0.1

Pas de corps de requête

   

Remarques sur l'alimentation des champs :

  • Authorization : Bearer < access_token précédemment récupéré>
  • X-Request-ID : <en-tête de corrélation de la requête émise>
  • Signature : <signature de la requête émise>
  • Psu-Ip-Address => permet de différencier les appels batch et les appels avec le PSU connecté : ce champ est à alimenter pour un PSU connecté

 

Réponse : 200 (=> OK)

Header :

X-request-id:id-1234567890111121 1

Body :

{

   "_links":{
      "self":{
         "templated":false,
         "href":"/stet/psd2/v1.4.2/accounts"
} 
},
   "accounts":[

      {
         "cashAccountType":"CACC",
         "accountId":{

            "iban":"FR7612579000920400430518020"
  
},
        
"usage":"PRIV",
         "psuStatus":"Account Holder",
         "name":"LEA SANDBOXA",
         "currency":"EUR"
 
},
       {

         "cashAccountType":"CACC",
         "accountId":{

            "iban":"FR7612579000920400851811524"
 
         
},
         "usage":"PRIV",
         "psuStatus":"Account Holder",
         "name":"LEA SANDBOXA",
         "currency":"EUR"
   
}

]

}

   

Exemple de requête en assemblage sandbox AVEC la méthode PUT /Consent au préalable:

GET https://www.12579.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts

Header :

Authorization:Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-Request-ID:id-1234567890111121 1 

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+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxinDocH1ne=\

Psu-IP-Address:192.168.0.1

Pas de corps de requête

   

Remarques sur l'alimentation des champs :

  • Authorization : Bearer < access_token précédemment récupéré>
  • X-Request-ID : <en-tête de corrélation de la requête émise>
  • Signature : <signature de la requête émise>
  • Psu-Ip-Address => permet de différencier les appels batch et les appels avec le PSU connecté : ce champ est à alimenter pour un PSU connecté

 

Réponse : 200 (=> OK)

Header :

X-request-id:id-1234567890111121 1

Body :

{

   "_links":{
      "self":{
         "templated":false,
         "href":"/stet/psd2/v1.4.2/accounts"
} 
},
   "accounts":[

 {
         "cashAccountType":"CACC",
         "accountId":{

            "iban":"FR7612579000920400430518020"
},
         "resourceId":"125790009204004305180",
         "_links":{

            "balances":{
               "templated":false,
               "href":"/stet/psd2/v1.4.2/accounts/125790009204004305180/balances"
     
},
            "transactions":{

               "templated":true,
               "href":"/stet/psd2/v1.4.2/accounts/125790009204004305180/transactions"
}
},
         "usage":"PRIV",
         "psuStatus":"Account Holder",
         "name":"LEA SANDBOXA",
         "currency":"EUR"
      

},
   {

         "cashAccountType":"CACC",
         "accountId":{

            "iban":"FR7612579000920400851811524"
},
         "resourceId":"125790009204008518115",
         "_links":{

            "balances":{
               "templated":false,
               "href":"/stet/psd2/v1.4.2/accounts/125790009204008518115/balances"
          
},
            "transactions":{

               "templated":true,
               "href":"/stet/psd2/v1.4.2/accounts/125790009204008518115/transactions"
           
}
         

},
         "usage":"PRIV",
         "psuStatus":"Account Holder",
         "name":"LEA SANDBOXA",
         "currency":"EUR"
   
}

]

}

 

2) Transmettre la liste des comptes consentis par le PSU

Cet appel vous permet de transmettre à l'ASPSP la liste des comptes consentis par le PSU. 

La description de la fonctionnalité est décrite dans le cas d'usage "Transmettre la liste des comptes". 

   

Exemple de requête en assemblage sandbox :

PUT https://www.12579.sandbox.api.89C3.com/stet/psd2/v1.4.2/consents

Headers :

Authorization:Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-Request-ID:id-1234567890111121 2

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+C2lVBNJrViMJBezFK7AYVjnSWH7t1QinCept10n=\

Psu-IP-Address:192.168.0.1

Body :
{

   "balances":[
      {
         "iban":"FR7612579000920400430518020"
  
},
      {

         "iban":"FR7612579000920400851811524"
}

],
   "transactions":[

      {
         "iban":"FR7612579000920400430518020"
},
      {

         "iban":"FR7612579000920400851811524"    
}
  
],
   "trustedBeneficiaries":false,
   "psuIdentity":false

}

 

Réponse : 201 (=> created)

Headers :

X-Request-ID : id-1234567890111121 2

Pas de body 

3) Obtenir le solde

Cet appel vous permet d'obtenir le solde d'un compte consenti.

La description de la fonctionnalité est décrite dans le cas d'usage "Obtenir les soldes d'un compte", et cette information n'est remontée que si un consentement PSU a été reçu au préalable par l'ASPSP via la méthode PUT /consents.

  

Exemple de requête en assemblage sandbox avec un {accountResourceId} = numéro de compte ciblé :

GET https://www.12579.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/125790009204004305180/balances

Headers :

Authorization:Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-Request-ID:id-1234567890111121 2

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+C2lVBNJrViMJBezFK7AYVjnSWH7t1Qincept10n=\

Response :

200 OK

Headers :

X-Request-ID:id-1234567890111121 2

Body :

{

    "balances": [

        {

            "balanceType": "CLBD",

            "name": "Solde comptable au 28/09/2018",

            "balanceAmount": {

                "amount": "-150.00",

                "currency": "EUR"

            }

        }

    ],

    "_links": {

        "self": {

            "templated": false,

            "href": "/stet/psd2/v1.4.2/accounts/125790009204004305180/balances"

        },

       },

        "parent-list": {

            "templated": false,

            "href": "/stet/psd2/v1.4.2/accounts"

        }

    }

}

  

4) Obtenir les transactions

Cet appel vous permet d'obtenir les transactions d'un compte consenti.

La description de la fonctionnalité est décrite dans le cas d'usage "Obtenez les transactions", et cette information n'est remontée que si un consentement PSU a été reçu au préalable par l'ASPSP via la méthode PUT /consents.

  

Exemple de requête en assemblage sandbox avec un {accountResourceId} = numéro de compte ciblé :

GET https://www.12579.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/125790009204004305180/transactions

  

Headers :

Authorization:Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf

X-Request-ID:id-1234567890111121 1

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+C2lVBNJrViMJBezFK7AYVjnSWH7t1T0tOtuTuT1ti=\

Psu-IP-Address:192.168.0.1

Pas de body

 

Réponse : 200 (=> OK)

  

Headers :

   X-Request-ID : id-1234567890111121 1

Body :

{

   "_links":{
      "balances":{
         "templated":false,
         "href":"/stet/psd2/v1.4.2/accounts/125790009204004305180/balances"
      

},
      "self":{
         "templated":true,
         "href":"/stet/psd2/v1.4.2/accounts/125790009204004305180/transactions"
      

},
      "parent-list":{
         "templated":false,
         "href":"/stet/psd2/v1.4.2/accounts"
   

}

   

},
   "transactions":{

         "resourceId":null,
         "remittanceInformation":[
            "Retrait Carte"
 
],

"entryReference":"257040043051802019-09-08-05.33.46.621234",

"transactionAmount":{

            "amount":"13.00",
            "currency":"EUR"
},
         "bookingDate":"2019-09-05",
         "creditDebitIndicator":"DBIT",
         "status":"BOOK"      
}
   

}

  

 

5) Obtenir l'identité du client

Cet appel vous permet d'obtenir l'identité du PSU connecté (qui n'est pas forcément le client possédant le compte).

La description de la fonctionnalité est décrite dans le cas d'usage "Obtenir l'identité du client", et cette information n'est remontée que si un consentement PSU a été reçu au préalable par l'ASPSP via la méthode PUT /consents.

Exemple de requête en assemblage sandbox :

GET https://www.12579.sandbox.api.89C3.com/stet/psd2/v1.4.2/end-user-identity

  

6) Rafraîchir le jeton d'accès

Cet appel vous permet de rafraichir le jeton d'accès avec le refresh-token. 

La description de la fonctionnalité est décrite dans la rubrique "Vue d'ensemble" > "Rafraîchir votre jeton". 

  

Exemple de requête en assemblage sandbox :

POST https://www.12579.sandbox.api.89C3.com/stet/psd2/oauth/token

  

Header : 

Content-Type:application/x-www-form-urlencoded; charset=utf-8

Params:

client_id:PSDFR-ACPR-13807

grant_type:refresh_token

refresh_token:KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAbCdEf

 

Réponse : 

{

   "access_token":"4s2Bt3MRL7nlPUZcRTPe5Tjs0v8p7ZOXOyEKs1juYesR2bel0t3v1aAp1s",
   "token_type":"Bearer",
   "expires_in":3600,
   "scope":"aisp offline_access",
   "refresh_token":"KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAbCdEf"

}