Obtenir les soldes d'un compte

Obtenez les soldes d'un compte à vue ou les encours des cartes à débit différé adossées à ce dernier !

  

➤ Cas d'usage

Ce service permet de récupérer la liste des soldes d'un compte à vue ou les encours d'une carte à débit différé du client.

Ce service fait suite à la restitution de la liste des comptes et cartes d'un client : un resourceId correspondant à un compte ou une carte doit être fourni pour obtenir la liste des soldes ou encours.

3 types de soldes seront retournés dans le cas d'un compte passé en paramètre :

  • Solde en valeur ("VALU" dans la norme STET) => solde affiché par rapport à une date de valeur
  • Solde Comptable ("CLBD" dans la norme STET) => solde comptable en fin de période (fin de semaine, fin de mois, fin de trimestre, fin de semestre, fin d’année)
  • Solde TP ("OTHR" dans la norme STET) => solde instantané (évolue en temps réel à chaque écriture sur le compte)

  

3 types d'encours seront retournés dans le cas d'une carte passée en paramètre :

  • Encours => montant des facturettes reportées au mois suivant
  • Encours terminé non prélevé => correspond au montant des facturettes du mois courant non encore comptabilisées
  • Encours terminé prélevé => correspond au montant des facturettes du mois précédent

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.

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.

En résumé, ce service permet de lister les soldes d'un compte à vue du client ou de lister les encours 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 le solde d'un compte à vue :

  • L'IBAN du compte doit nous avoir été transmis dans la liste "balances" 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 courant, 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 tel que "accountId": {"iban":"" }

  • L'URI pour l'accès à cette méthode est donnée via la rubrique "_links": {"balances":"{"href": ...}} en résultat de la requête GET /accounts pour le "resourceId" du compte à vue

Pour récupérer les encours 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 "balances" 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":"" }

  • L'URI pour l'accès à cette méthode est donnée via la rubrique "_links": {"balances":"{"href": ...}} en résultat de la requête GET /accounts pour le "resourceId" de la carte à débit différé.

 

➤ Requête

Requête "GET /accounts/{accountResourceId}/balances"

book picto Voir aussi la spécification de place STET V1.4.2.17 / Part II / Section 4.3.4 / page 31 

 

➤ Paramètres obligatoires ou facultatifs du body requis pour l'appel de ce service

Paramètre accountResourceId : compte à vue pour lequel on veut consulter les soldes ou carte à débit différé pour laquelle on veut consulter les encours, cette donnée correspond à la rubrique "resourceId" obtenue dans la page de résultat de la requête GET /accounts.

Paramètre facultatif : PSU-IP-ADDRESS => à alimenter si le PSU est connecté.

  

➤ Résultat retourné

Cet appel permet de récupérer :

  • la liste des soldes pour le compte à vue passé en paramètre
  • ou la liste des encours de la carte à débit différé passée en paramètre.

 

3 types de soldes seront retournés dans le cas d'un compte à vue passé en paramètre :

Solde en valeur ("VALU" dans la norme STET) => solde affiché par rapport à une date de valeur
Solde Comptable ("CLBD" dans la norme STET) => solde comptable en fin de période (fin de semaine, fin de mois, fin de trimestre, fin de semestre, fin d’année)
Solde TP ("OTHR" dans la norme STET) => solde instantané (évolue en temps réel à chaque écriture sur le compte)

 

3 types d'encours pourront être retournés dans le cas d'une carte passée en paramètre :

Encours => montant des facturettes reportées au mois suivant
Encours terminé non prélevé => correspond au montant des facturettes du mois courant non encore comptabilisées
Encours terminé prélevé => correspond au montant des facturettes du mois précédent

 

Un lien self sera également présent pour revenir à la page obtenue 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é.

  

➤ Exemple

Requête

"GET /stet/psd2/v1.4.2/accounts/038-CPT30019654051/balances"

Un exemple de requête est fourni dans la rubrique "Comment tester l'API ?" > "Assemblage sandbox".

Les jeux de données de tests sont décrits dans la rubrique "Comment tester l'API ?" > "Tester nos personas".

book picto Voir aussi la spécification de place STET V1.4.2.17 / Part III / Section 6.4 / page 9 

 

Résultat

Status code : 200

 

Body

{
  "balances": [
    {
      "balanceType": "VALU",
      "name": "Solde en Valeur",
      "balanceAmount": {
        "amount": "2165.5",
        "currency": "EUR"
      },
      "referenceDate": "2020-06-08"
    },
    {
      "balanceType": "CLBD",
      "name": "Solde Comptable",
      "balanceAmount": {
        "amount": "2165.5",
        "currency": "EUR"
      },
      "referenceDate": "2020-06-07"
    },
    {
      "balanceType": "OTHR",
      "name": "Solde TP",
      "balanceAmount": {
        "amount": "2165.5",
        "currency": "EUR"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/balances"
    },
    "transactions": {
      "href": "https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts/038-CPT30019654051/transactions"
    },
    "parent-list": {
      "href": "https://www.rs-sandbox.api.89c3.com/stet/psd2/v1.4.2/accounts"
    }
  }
}

(cas du persona Marc - D0999990I0)

  

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

ErreurDescription 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)
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é
IPSU InvalidPSU : Numéro d'abonné non référencé ou abonnement banque à distance résilié

  

➤ 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. Ils devront être validés avant tout déploiement applicatif en production.

 

Description du testJeu de données et Résultat attendu

Récupération du solde d'un compte

=> Vérification des liens présents dans le résultat de la requête (lien self, soldes et transactions)

Persona : Marc - 038-CPT30019654051

Prérequis : scope OAuth2 = aisp

Résultat :

réponse HTTP 200 => OK

restitution des trois soldes du compte de paiement

Récupération de tous les soldes d'un compte, les soldes sont à 0

=> Vérification des liens présents dans le résultat de la requête (lien self, soldes et transactions)

Persona : Adam - 038-CPT30319665741

Prérequis : scope OAuth2 = aisp

Résultat

réponse HTTP 200 => OK

restitution des trois soldes du compte de paiement

les soldes sont à 0

Récupération des soldes liés à un compte inconnu

Persona : Inconnu - 038-CPT30014684067

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

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