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 |