Obtenir les transactions
Obtenez l'historique des transactions d'un compte à vue ou les facturettes des cartes à débit différé adossées à ce dernier !
➤ Cas d'usage
Ce service permet de récupérer la liste des opérations d'un compte à vue ou la liste des facturettes d'une carte à débit différé du client.
Les transactions obtenues sont inférieures ou égales à 90 jours par rapport à la date du jour.
Une pagination de la liste renvoyée peut être faite s'il y a beaucoup de données à afficher, dans ce cas des liens donnant accès à la première page, la précédente, la suivante et la dernière page faciliteront la consultation des résultats.
Ce service fait suite à la restitution de la liste des comptes à vue et cartes à débit différé d'un client : un resourceId correspondant à un compte ou une carte doit être fourni pour obtenir la liste des transactions.
Les accès à cette méthode sont limités à 4 accès batch maximum par jour calendaire, pour un client et pour un compte / une carte à débit différé donnés, hors pagination.
En résumé, ce service permet de lister les transactions d'un compte à vue du client ou de lister les facturettes d'une carte à débit différé adossée à ce compte à vue.
➤ Prérequis
Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité et d'avoir récupéré le jeton d'accès OAUTH2 (voir la rubrique "Vue d'ensemble" > "Récupérer votre jeton").
Pour récupérer les transactions d'un compte à vue :
L'IBAN du compte à vue doit nous avoir été transmis dans la liste "transactions" de la méthode PUT /consents et ne doit pas avoir été révoqué depuis (<=> pas d'annule et remplace via PUT /consents sans cet IBAN dans la liste "transactions")
L "accountResourceId" permettant d'interroger cette méthode pour ce compte à vue, est récupéré via le résultat de la requête GET /accounts dans la rubrique "resourceId" pour le compte à vue correspondant à cet IBAN, c'est à dire "accountId": {"iban":"<IBAN du compte à vue>" }
L'URI pour l'accès à cette méthode est donnée via la rubrique "_links": {"transactions": {"href": ...}} en résultat de la requête GET /accounts pour le "resourceId" du compte à vue
Pour récupérer les transactions d'une carte à débit différé adossée à un compte à vue :
L'IBAN du compte à vue auquel est adossée la carte à débit différé doit nous avoir été transmis dans la liste "transactions" de la méthode PUT /consents et ne doit pas avoir été révoqué depuis (<=> pas d'annule et remplace via PUT /consents sans cet IBAN dans la liste "transactions")
L "accountResourceId" permettant d'interroger cette méthode pour la carte à débit différé, est récupéré via le résultat de la requête GET /accounts dans la rubrique "resourceId" pour la carte à débit différé, c'est à dire :
tel que "accountId" : {"other": {"schemeName" : "CPAN"}} avec "linkedAccount" qui correspond au "resourceId" du compte à vue
avec le "resourceId" du compte à vue récupéré via la requête GET /accounts et tel que "accountId" : {"iban":"<IBAN du compte à vue>"}
L'URI pour l'accès à cette méthode est donnée via la rubrique "_links" : {"transactions": {"href": ...}} en résultat de la requête GET /accounts pour le "resourceId" de la carte à débit différé
➤ Requête
GET /account/{accoundResourceId}/transactions
Voir aussi la spécification de place STET V1.4.2.17 / Part II / section 4.4 / page 34
➤ Paramètres obligatoires ou facultatifs du body requis pour l'appel de ce service
Paramètres obligatoires : accountResourceId => compte à vue pour lequel on veut consulter les opérations ou carte à débit différé pour laquelle on veut consulter les facturettes.
Paramètres facultatifs :
- dateFrom => date limite de début pour les transactions recherchées. Les transactions ayant une date d’imputation égale au paramètre dateFrom sont restituées dans le résultat.
- dateTo => date limite de fin pour les transactions recherchées. Les transactions ayant une date d’imputation égale au paramètre dateTo ne sont pas restituées dans le résultat.
- entryReferenceFrom => référence d'incrément minimum pour l'identifiant technique. Seules les transactions avec une entryReference strictement plus grande que entryReferenceFrom sont restituées
- entryReferenceTo => référence d'incrément maximum pour l'identifiant technique. Seules les transactions avec une entryReference plus petite ou égale que entryReferenceTo sont restituées
- PSU-IP-ADDRESS => à alimenter si le client est connecté
Le format autorisé pour les données dateFrom et dateTo est YYYY-MM-DD.
➤ Résultat retourné
Cet appel permet de récupérer :
- la liste des opérations pour le compte passé en paramètre
- la liste des facturettes de la carte à débit différé passée en paramètre
La date des transactions obtenue est inférieure ou égale à 90 jours par rapport à la date du jour.
Une pagination de la liste renvoyée peut être faite s'il y a beaucoup de données à afficher, dans ce cas des liens de navigation donnant accès à la première page, à la page précédente, à la suivante et à la dernière page, faciliteront la consultation des résultats.
Un lien self sera également présent pour revenir à la page obtenue juste après exécution de la requête.
Vos accès à cette méthode sont limités à 4 accès batch maximum par jour calendaire, pour un client et pour un compte à vue ou une carte à débit différé donnés (modulo la pagination éventuelle). En revanche, lorsque c'est le client connecté qui interroge directement ses comptes à vue, le nombre d'accès n'est pas limité.
BookingDate est reportée dans expectedBookingDate lorsque le mouvement n'est pas comptabilisé (status = « PDNG »)
La remittance information contient un nouvel objet intermédiaire "unstructured"
Suppression du champ "entryReference" lorsqu'il n'est pas renseigné (status = "PDNG")
Alimentation du champ "bankTransactionCode".
Les facturettes des cartes à débit différé qui ne sont pas comptabilisées sont au status = « OTHR ».
➤ Précisions sur les types d'opération
| Types d’opérations remontés |
|---|
| Virement émis |
| Virement reçu |
| Prélèvement émis |
| Prélèvement reçu |
| Intérêts |
| Frais et commissions |
| Extourne et rétrocession |
| Effets |
| Titres et instruments financiers |
| Chèques |
| Cartes |
| Incidents et impayés |
| Prêts |
| International |
| Espèces retrait et versement |
| Autres |
Cela se décline dans la sandbox, en 73 libellés de code opération différents pour les 4 500 transactions du persona « SARL UNIPERSONNELLE 2640 » :
| Libellé code opération | Type d'opération associé |
|---|---|
| ACHAT PARTS BP | Titres et instruments financiers |
| ANN VIR SEPA | Virement émis |
| ANNU EUROVIR | Virement émis |
| ANNUL FRAIS CB | Extourne et rétrocession |
| ANNULATION | --- |
| ANNULATION PRLV | --- |
| ARRETE DE CPTE | Intérêts |
| CASH POOLING | --- |
| CHEQUE BANQUE | Chèques |
| CHEQUE | Chèques |
| CHEQUE BANQUE | --- |
| COM.GESTION DEB | --- |
| DEBIT DIFFERE | Cartes |
| DEPLACE | Chèques |
| DEPOT ESPECES | Espèces retrait et versement |
| ECH PRET IMPAYE | --- |
| ECHEANCE PRET | Prêts |
| ENVOI EXTRAITS | --- |
| EUROPRELEVEMENT | Prélèvement reçu |
| EUROVIR OCCAS | Virement émis |
| EUROVIR PERM | Virement émis |
| EUROVIR SEPA | Virement émis |
| EUROVIR SEPA | Virement reçu |
| EUROVIR SEPA RJ | Autres |
| FACT. CB | --- |
| FACTURE CB | Cartes |
| FACTURETTES CB | --- |
| FRAIS ANNUL EVI | Virement reçu |
| FRAIS OU COTIS | Frais et commissions |
| FRAIS OU COTIS | --- |
| FRAIS VIREMENT | Virement émis |
| IMP.CARTE BLEUE | Incidents et impayés |
| IMPAYE EUROPRLV | Virement reçu |
| INTERETS RETARD | International |
| LCR DOMICILIEE | Effets |
| PRELEVEMENT | Prélèvement reçu |
| RAP COMMERCIAL | International |
| REGUL.INT.CPTE | --- |
| REM.CARTE BLEUE | Cartes |
| REM.ENCAISSEMEN | Effets |
| REMBT EUROPREL | --- |
| REMBT EUROPREL | Virement reçu |
| REMISE EUROPRL | Prélèvement émis |
| REMISE EUROPRLV | Prélèvement émis |
| REMISES CHEQUES | Chèques |
| RETOUR EUROPREL | --- |
| RETRAIT CAISSE | Espèces retrait et versement |
| RETRAIT DISTRIB | Cartes |
| RETRAIT UNIQUE | Espèces retrait et versement |
| RETRO FR.CHEQUE | --- |
| REVERSEMEN DCC | --- |
| REVRST EUROPREL | Virement reçu |
| REVRST EUROPRLV | --- |
| REVRST EUROPRV | --- |
| TRANSFERT SOLDE | Espèces retrait et versement |
| VERST DEPLACE | Espèces retrait et versement |
| VERST RAPIDE | Espèces retrait et versement |
| VI TRESORERIE | Virement émis |
| VI TRESORERIE | Virement reçu |
| VIR ADMCP CYBER | Virement émis |
| VIR EURO SIMPLE | Virement reçu |
| VIR INSTAN EMIS | Virement émis |
| VIR INSTAN RECU | Virement émis |
| VIR INTERNAT | Prêts |
| VIR TRESO CYBER | Virement émis |
| VIR.AUTOMATIQUE | Virement émis |
| VIREMENT | Virement émis |
| VIREMENT | Virement reçu |
| VIREMENT CREDIT | Virement reçu |
| VIREMENT DEBIT | Virement émis |
| VIREMENT EMIS | Virement émis |
| VIRT PERMANENT | Virement émis |
La norme STET v1.4.2.17 est appliquée : le champ remittanceInformation que notre API DSP2 renvoie est non structurée (utilisation de la balise « unstructured » contenant un tableau de String).
➤ Exemple
Requête 1
GET /stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions?dateFrom=2019-06-03&dateTo=2019-06-09
Un exemple plus complet de requête est fourni dans la rubrique "Comment tester l'API ?" > "Assemblage sandbox".
Voir aussi la spécification de place STET V1.4.2.17 / Part III / Section 6.5 / page 10
Résultat 1
Status code : 200
Body
{ |
(cas du persona Marc -D0999990I0)
Requête 2
GET /stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions?dateFrom=2019-06-03&dateTo=2019-06-09
Résultat 2 avec pagination
Status code : 200
Body
{ |
(Cas du persona Sarl Unipersonnelle 2640- D0999995I0)
Requête 3 - Récupération des facturettes d’une carte CB à débit différé
GET /stet/psd2/v1.4.2/accounts/accounts/038-GFCC01w_pPEk8N32abYfHO0xRDlA/transactions
Résultat 3
Status code : 200
Body
{ |
(Cas du persona Alix- D0999992I0)
Codes erreurs
Voici la liste de descriptions des codes erreurs de ce service. Il y a une annotation rouge pour ceux étant définis CFONB.
Lien vers la description de la méthode et des codes retour http
| Erreur | Description de l'erreur |
|---|---|
| AC01 (CFONB) | IncorrectAccountNumber : le numéro de compte est incorrect ou inconnu |
| AC04 (CFONB) | ClosedAccountNumber : le compte est clos |
| AC06 (CFONB) | BlockedAccount : le compte est bloqué / fait l'objet d'une opposition |
| BE05 (CFONB) | UnrecognisedInitiatingParty : l'AISP est inconnu |
| BADS | BadScope : l'appel au service a été fait avec un jeton CBPII (AISP attendu) |
| ENDE | EntriesDatesError : une ou des dates sont erronées |
| IPGN | InvalidPageNumber : le numéro de page est invalide |
| INTE | InternalError : il y a une erreur interne de traitement |
| INTS | InternalServerError : il y a une erreur interne de communication avec le SI |
| NGAC | NotGrantedAccount : le compte n'est pas consenti |
| NIMP | NotImplemented : le mauvais verbe est appelé (GET attendu) |
| TMRQ | TooManyRequest : le nombre de requêtes possibles a été dépassé |
| RENF | ReferenceNotFound : la référence de la transaction est inexistante |
| IPSU | InvalidPSU : Numéro d'abonné non référencé ou abonnement banque à distance résilié |
| FF01 | Bad Request : le format de la requête est incorrect |
| NAAC | NotAvailableAccounts : absence de comptes éligibles |
| CDNA | CardNotAvailable ! la carte à débit différé n'est pas ou plus accessible |
➤ Test d'acceptance
Ces cas de tests ont pour objectif de vous permettre d'effectuer un minimum de tests afin de prendre en main cette API et d'y accéder depuis votre application.
| Description du test | Jeu de données |
|---|---|
Récupération de toutes les transactions d'un compte (sous 90 jours) => Vérification des liens présents dans le résultat de la requête (lien self, soldes et transactions) | Persona : Alix - 038-CPT30019654081 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions du compte de paiement et de la liste de facturettes de la carte à débit différée |
Récupération des transactions d'un compte et vérification que l'ASPSP gère correctement le mécanisme de pagination =>Vérification des liens optionnels premier, précédent, suivant, dernier. | Persona : Alix - 038-CPT30019654081 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution de la liste paginée des transactions du compte avec trois éléments par page |
Récupération des transactions liées à un compte inconnu | Persona : Inconnu - CPT310197919611 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 404 => compte inconnu message d'erreur : AC01 |
Requête HTTP avec un jeton d'accès non autorisé pour la ressource (scope erroné, par exemple "extended_transaction_history" qui n'est pas géré par les Banques Populaires) | Persona : Marc - 038-CPT30019654051 Prérequis : scope OAuth2 <> aisp Résultat : réponse HTTP 403 => accès à la ressource refusé message d'erreur : BADS |
Passage d'une requête HTTP POST | Persona : Marc - 038-CPT30019654051 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 405 => méthode non autorisée |
=>Vérification que le filtre est bien appliqué | Persona : Alix - 038-CPT30019654081 dateFrom : mettre "la date du jour - 8 jours" Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ultérieures à la date donnée en entrée |
Récupérer la liste des transactions en précisant une date de fin =>Vérification que le filtre est bien appliqué | Persona : Alix - 038-CPT30019654081 dateTo : mettre "la date du jour - 1 jour" Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions antérieures à la date donnée en entrée dans la limite des 90 jours d'ancienneté |
Récupérer la liste des transactions en précisant une référence d'incrément minimum pour l'identifiant technique =>Vérification que le filtre est bien appliqué | Persona : Alix - 038-CPT30019654081 afterEntryReference : 3 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ayant un incrément supérieur à celui donné en entrée |
Récupérer la liste des transactions en précisant une date de début et une date de fin =>Vérification que le filtre est bien appliqué | Persona : Alix - 038-CPT30019654081 dateFrom : mettre "la date du jour - 8 jours" dateTo : mettre "la date du jour - 2 jours" Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions comprises entre la date de début et la date de fin |
Récupérer la liste des transactions en précisant une date de début et une référence d'incrément minimum pour l'identifiant technique =>Vérification que le filtre est bien appliqué | Persona : Alix - 038-CPT30019654081 dateFrom : mettre "la date du jour - 8 jours" afterEntryReference : 2 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ayant un incrément supérieur à celui donné en entrée et une date supérieure à celle donnée en entrée |
Récupérer la liste des transactions en précisant une date de fin et une référence d'incrément minimum pour l'identifiant technique =>Vérification que le filtre est bien appliqué | Persona : Alix - 038-CPT30019654081 dateTo : mettre "la date du jour - 2 jours" afterEntryReference : 2 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ayant un incrément supérieur à celui donné en entrée et une date inférieure à celle donnée en entrée |
|
=>Vérification que le filtre est bien appliqué | Persona : Alix - 038-CPT30019654081 dateFrom : mettre "la date du jour - 8 jours" dateTo : mettre "la date du jour - 2 jours" afterEntryReference : 2 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK restitution des transactions ayant un incrément supérieur à celui donné en entrée et une date comprise entre celles données en entrée |
Passage d'une requête pour avec une période de transactions demandée supérieure à 90 jours | Persona : Alix - 038-CPT30019654081 dateFrom : mettre "la date du jour - 92 jours Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 400 => requête erronée, période non autorisée message d'erreur : ENDE |
Passage d'une requête de récupération des transactions avec une date au format incorrect | Persona : Alix - 038-CPT30019654081 dateFrom : mettre une date au format incorrect Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 400 => requête erronée message d'erreur : ENDE |
Passage d'une requête de récupération des transactions avec plus de 200 transactions en résultat => Vérifier qu'il y ait bien 200 transactions sur la première page (pagination) | Persona : Adam - 038-CPT30319665742 Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK 245 transactions sont retournées sur deux pages avec une profondeur d'historique de trois mois |
Passage de requêtes de récupération des transactions avec 4 500 transactions en résultat en tout pour 5 comptes et une carte à débit différé. 73 typologies / codes opérations différents sont restitués. => Vérifier qu'il y ait bien 200 transactions sur la première page (pagination) lorsque plus de 200 transactions sont récupérées | Persona : SARL UNIPERSONNELLE 2640
Prérequis : scope OAuth2 = aisp Résultat : réponse HTTP 200 => OK |