BTP Banque – Disponibilité des fonds

Comment réduire son risque d'impayé

Ce service permet de vérifier la disponibilité des fonds pour le compte de notre client pour un montant donné d’une transaction.

Un client porteur de votre carte de crédit privative effectue une transaction sur un site d’e-commerce avec celle-ci. Le client a donné, au préalable, une délégation à votre établissement, ainsi qu’un consentement explicite à son teneur de compte dans lequel est domicilié le prélèvement de la carte.

Via cette API « disponibilité des fonds » mise à disposition par la banque, vous pouvez demander en temps réel la confirmation que le client ait suffisamment de fonds sur son compte pour couvrir le montant de cette transaction SANS lui demander ses identifiants de connexion en ligne, réduisant de fait votre exposition au risque d’impayé.

Le teneur de comptes répond positivement ou négativement sans aucun blocage de fonds correspondant au montant de la transaction, ni validation de celle-ci.

Les ressources de cette API ne peuvent être consommées que par des prestataires ayant le rôle d’émetteurs d’instruments de paiement liés à une carte (« CBPII » ou « PIISP » suivant la version STET), ce prérequis étant décrit dans voir la section « Éligibilité ».

Une fois les prérequis remplis, le processus global est le suivant :

1- Vous avez établi un contrat avec le client et lui délivrez une carte avec prélèvement domicilié chez le teneur de compte. Il vous l’indique à travers vos interfaces.

2- Lors du premier échange avec les infrastructures du teneur de compte, vous allez faire une demande de jeton d’autorisation (et un jeton de rafraichissement). Le principe de base est, qu’en tant que TPP CBPII, vous devez obtenir ces jetons AVANT de consommer les ressources de l’API. Ce jeton est généré par le teneur de compte (ASPSP) APRES avoir identifié et authentifié le client.

En tant que teneur de compte, nous allons :

• vérifier vos certificats et agréments ;
• et via le jeu de la redirection, nous allons identifier et authentifier fortement le client afin de récupérer son consentement et de générer le jeton d’accès.

3- Si l’autorisation est accordée par le client, vous pourrez ensuite récupérer un jeton d’accès OAUTH2 (et son jeton de rafraichissement) via des échanges sécurisés avec la plateforme BPCE API (voir le cas d’usage « Récupérez votre jeton d’accès !« ).

4- En présentant ce jeton d’autorisation valable 180 jours, vous pourrez alors consommer les ressources de l’API « disponibilité des fonds » et réduire votre risque d’impayé en interrogeant la banque sur l’existence de la provision sur le compte du client correspondant au montant du paiement (voir le cas d’usage « Consommez et vérifiez la disponibilité des fonds ! »).

Au bout du délai réglementaire de 180 jours, ce processus devra être reconduit (voir le cas d’usage « Rafraichissez votre jeton !« ).

NB : le gestionnaire de compte ASPSP a possibilité de vous refuser l’accès pour différents motifs justifiés (API non conforme, compte bloqué entre-temps, etc..).

Récupérer votre jeton

L’accès aux API « information sur compte » ou « disponibilité des fonds » vous est autorisé via un jeton d’accès (access_token) qui peut être obtenu en appliquant le standard de place OAUTH2.

Cinématique de récupération du jeton d’autorisation

1. Notre client (PSU) vous indique l’identité de son établissement de compte.

2. Vous initiez la séquence de récupération du jeton d’accès OAuth2 en redirigeant le client (PSU), via son navigateur internet, vers l’infrastructure informatique d’autorisation de l’établissement teneur de compte (ASPSP) et en utilisant la commande : GET /authorize

Voir aussi la spécification de place STET V1.4.0.47 / Part I / section 3.4.3.2 / page 21

3. Le teneur de compte (ASPSP) va :

• Identifier et authentifier son client par l’une des méthodes d’authentification forte qu’elle propose et qu’il présente au client ;

• Effectuer des vérifications liées à votre profil en tant qu’AISP ou CBPII (validité de vos certificats QWAC et QSEALC et de votre rôle, non révocation de votre profil, etc.)

4. Une fois ces vérifications effectuées et si elles sont concluantes, l’établissement bancaire va rediriger le client (PSU) vers votre site en utilisant votre URL de « call-back » (redirection) que vous nous aurez transmise lors du processus de « Go Live ».

En effet, l’AISP doit préciser pour son APP consommatrice, une URL qui sera appelée par l’établissement bancaire :

• 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 d’identification et d’authentification est interrompue à l’une de ses étapes (exemple : timeout sur l’écran d’identification ou sur l’écran d’authentification forte).

Si le PSU vous a autorisé à récupérer ses données chez son teneur de compte, vous trouverez dans la réponse à cet appel un code à utilisation unique qui a une durée de vie courte.

5. Via un appel de type POST /token, vous allez pouvoir alors demander directement au teneur de compte votre jeton d’accès OAUTH2 (access_token) avec les éléments reçus précédemment dont le code à utilisation unique.

NB : les requêtes /token du flow Authorization Code doivent être envoyée SANS le paramètre « scope ».

Voir aussi la spécification de place STET V1.4.0.47 / Part I / section 3.4.3.2 / page 22

6. L’établissement teneur de compte (ASPSP) va :

• Effectuer des vérifications liées à votre profil en tant qu’AISP ou CBPII (validité des certificats et de votre agrément, non révocation de votre profil, etc.)
• Vous identifier et vous authentifier en tant qu’AISP ou CBPII via votre certificat que vous mettrez à disposition pour sécuriser l’échange mutuel.

7. Une fois ces vérifications effectuées et si elles sont concluantes, le teneur de compte va vous renvoyer une réponse HTTP200 (OK) contenant, entres autres, le jeton d’accès OAUTH2 (access_token).

Voir aussi la spécification de place STET V1.4.0.47 / Part I / section 3.4.3.2 / page 23

8. Dès que le jeton d’accès OAUTH2 (access_token) délivré par la banque a été récupéré par vos soins, vous pourrez le présenter pour pouvoir consommer les ressources de l’API.

Ce jeton est accompagné d’un refresh_token valable 180 jours que vous devez conserver. Lorsque votre access_token arrive à expiration, vous pouvez en redemander un nouveau en suivant la rubrique « Vue d’ensemble » > « Rafraîchir votre jeton« .

Au bout de 180 jours votre refresh_token arrive à expiration. Pour en récupérer un nouveau, vous devrez reprendre cette cinématique « Récupérer votre jeton » et passer, de facto, par une nouvelle étape d’authentification forte du client auprès de son établissement bancaire (cf. point 3. ci-dessus).

Pour plus de détails, voir aussi OAUTH 2.0 Authorization Framework : https://tools.ietf.org/html/rfc6749#section-4.1

Exemple

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

Rafraîchir votre jeton

Principe

Les jetons OAUTH2 ayant une durée de vie limitée, il vous est nécessaire d’en demander le rafraîchissement avant son expiration.

Règles de base

Le teneur de compte (ASPSP) dispose au plus d’un jeton d’accès (access_token) et d’un jeton de rafraîchissement (refresh_token) valides par triplet client PSU / TPP / rôle AISP ou CBPII.

• Le jeton d’accès a une durée de validité courte (de l’ordre d’une heure max) sur un périphérique ou une application de notre client

• Le jeton de rafraîchissement a une durée de vie de 180 jours

• Le jeton de rafraîchissement et le jeton d’accès doivent pouvoir être révoqués à tout moment

• Si le jeton d’accès est révoqué alors le jeton de rafraîchissement doit l’être aussi et réciproquement

Cinématique du rafraîchissement de votre jeton d’accès (access_token)

1. Vous demandez le renouvellement du jeton d’accès auprès de l’ASPSP

2. L’ASPSP initie le renouvellement du jeton d’accès

3. L’ASPSP récupère le certificat du TPP auprès du référentiel de place

4. L’ASPSP contrôle la validité et la non révocation du certificat présenté

5. L’ASPSP contrôle la date de la dernière authentification (< 180 jours)

6. L’ASPSP vous transmet le nouveau jeton d’accès et l’ancien jeton de rafraîchissement

7. Vous stockez le jeton d’autorisation et l’ancien jeton de rafraîchissement de façon sûre

8. L’ASPSP invalide l’ancien jeton d’autorisation

Exemple

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

Publications réglementaires

/stet/psd2/v1/accounts/{accountResourceId}/balances

accountsBalances

Résumé

Retrieval of an account balances report (AISP)

Description

Description
This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification

• The ASPSP must provide at least the accounting balance on the account.
• The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible.
• Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
• The TPP has previously retrieved the list of available accounts for the PSU

Business flow
The AISP requests the ASPSP on one of the PSU’s accounts. The ASPSP answers by providing a list of balances on this account.

• The ASPSP must provide at least the accounting balance on the account.
• The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible.
• Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.

Scopes

• aisp
• piisp
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1/accounts

accounts

Résumé

Retrieval of the PSU accounts (AISP)

Description

Description
This call returns all payment accounts that are relevant the PSU on behalf of whom the AISP is connected. Thanks to HYPERMEDIA, each account is returned with the links aiming to ease access to the relevant transactions and balances. The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role.
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

Business Flow
The TPP sends a request to the ASPSP for retrieving the list of the PSU payment accounts. The ASPSP computes the relevant PSU accounts and builds the answer as an accounts list. The result may be subject to pagination in order to avoid an excessive result set. Each payment account will be provided with its characteristics.

Scopes

• aisp
• extended_transaction_history
• piisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1/accounts/{accountResourceId}/transactions

accountsTransactions

Résumé

Retrieval of an account transaction set (AISP)

Description

Description
This call returns transactions for an account for a given PSU account that is specified by the AISP through an account resource identification. The request may use some filter parameter in order to restrict the query

• on a given imputation date range
• past a given incremental technical identification

The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) is any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
• The TPP has previously retrieved the list of available accounts for the PSU

Business flow
The AISP requests the ASPSP on one of the PSU’s accounts. It may specify some selection criteria. The ASPSP answers by a set of transactions that matches the query. The result may be subject to pagination in order to avoid an excessive result set.

Scopes

• aisp
• extended_transaction_history
• piisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1/consents

consents

Résumé

Forwarding the PSU consent (AISP)

Description

Description
In the mixed detailed consent on accounts

• the AISP captures the consent of the PSU
• then it forwards this consent to the ASPSP

This consent replaces any prior consent that was previously sent by the AISP.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role.
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

Business Flow
The PSU specifies to the AISP which of his/her accounts will be accessible and which functionalities should be available. The AISP forwards these settings to the ASPSP. The ASPSP answers by HTTP201 return code.

Scopes

• aisp
• piisp
• extended_transaction_history

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1/funds-confirmations

fundsConfirmations

Résumé

Payment coverage check request (PIISP)

Description

Description
The PIISP can ask an ASPSP to check if a given amount can be covered by the liquidity that is available on a PSU cash account or payment card.

Prerequisites

• The TPP has been registered by the Registration Authority for the PIISP role
• The TPP and the PSU have a contract that has been registered by the ASPSP
  • At this step, the ASPSP has delivered an « Authorization Code », a « Resource Owner Password » or a « Client Credential » OAUTH2 access token to the TPP (cf. § 3.4.2).
  • Each ASPSP has to implement either the « Authorization Code »/ »Resource Owner Password » or the « Client Credential » OAUTH2 access token model.
  • Doing this, it will edit the [security] section on this path in order to specify which model it has chosen
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU.

Business flow
The PIISP requests the ASPSP for a payment coverage check against either a bank account or a card primary identifier.
The ASPSP answers with a structure embedding the original request and the result as a Boolean.
Scopes

• extended_transaction_history
• piisp
• aisp

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1/trusted-beneficiaries

trustedBeneficiaries

Résumé

Retrieval of the trusted beneficiaries list (AISP)

Description

Description
This call returns all trusted beneficiaries that have been set by the PSU. Those beneficiaries can benefit from an SCA exemption during payment initiation. The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role.
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

Business Flow
The AISP asks for the trusted beneficiaries list. The ASPSP answers with a list of beneficiary details structure.

Scopes

• piisp
• extended_transaction_history
• aisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/accounts/{accountResourceId}/balances

accountsBalances

Résumé

Retrieval of an account balances report (AISP)

Description

This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification
– The TPP has been registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
– The TPP has previously retrieved the list of available accounts for the PSU
The AISP requests the ASPSP on one of the PSU’s accounts.
The ASPSP answers by providing a list of balances on this account. – The ASPSP must provide at least the accounting balance on the account. – The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible. – Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.

Scopes

• cbpii
• aisp
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/accounts

accounts

Résumé

Retrieval of the PSU accounts (AISP)

Description

This call returns all payment accounts that are relevant the PSU on behalf of whom the AISP is connected.
Thanks to HYPERMEDIA, each account is returned with the links aiming to ease access to the relevant transactions and balances.
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results. – The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The TPP sends a request to the ASPSP for retrieving the list of the PSU payment accounts.
The ASPSP computes the relevant PSU accounts and builds the answer as an accounts list. The result may be subject to pagination in order to avoid an excessive result set. Each payment account will be provided with its characteristics.

Scopes

• extended_transaction_history
• cbpii
• aisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/accounts/{accountResourceId}/transactions

accountsTransactions

Résumé

Retrieval of an account transaction set (AISP)

Description

This call returns transactions for an account for a given PSU account that is specified by the AISP through an account resource identification.
The request may use some filter parameter in order to restrict the query – on a given imputation date range – past a given incremental technical identification
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.
– The TPP has been registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) is any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
– The TPP has previously retrieved the list of available accounts for the PSU
The AISP requests the ASPSP on one of the PSU’s accounts. It may specify some selection criteria.
The ASPSP answers by a set of transactions that matches the query. The result may be subject to pagination in order to avoid an excessive result set.
The default transaction set, in the absence of filter query parameter, has to be specified and documented by the implementation.

Scopes

• aisp
• cbpii
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/consents

consents

Résumé

Forwarding the PSU consent (AISP)

Description

In the mixed detailed consent on accounts
– the AISP captures the consent of the PSU
– then it forwards this consent to the ASPSP
This consent replaces any prior consent that was previously sent by the AISP.
– The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
The PSU specifies to the AISP which of his/her accounts will be accessible and which functionalities should be available.
The AISP forwards these settings to the ASPSP.
The ASPSP answers by HTTP201 return code.

Scopes

• aisp
• extended_transaction_history
• cbpii

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/end-user-identity

endUserIdentity

Résumé

Retrieval of the identity of the end-user (AISP)

Description

This call returns the identity of the PSU (end-user).
– The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The AISP asks for the identity of the PSU. The ASPSP answers with the identity, i.e. first and last names of the end-user.

Scopes

• aisp
• extended_transaction_history
• cbpii

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/funds-confirmations

fundsConfirmations

Résumé

Payment coverage check request (CBPII)

Description

The CBPII can ask an ASPSP to check if a given amount can be covered by the liquidity that is available on a PSU cash account or payment card.
– The TPP has been registered by the Registration Authority for the CBPII role
– The TPP and the PSU have a contract that has been registered by the ASPSP – At this step, the ASPSP has delivered an « Authorization Code », a « Resource Owner Password » or a « Client Credential » OAUTH2 access token to the TPP (cf. § 3.4.2). – Each ASPSP has to implement either the « Authorization Code »/ »Resource Owner Password » or the « Client Credential » OAUTH2 access token model. – Doing this, it will edit the [security] section on this path in order to specify which model it has chosen
– The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 « Authorization Code », « Resource Owner Password » or « Client Credential » access token which allows the ASPSP to identify the relevant PSU.
The CBPII requests the ASPSP for a payment coverage check against either a bank account or a card primary identifier.
The ASPSP answers with a structure embedding the original request and the result as a Boolean.

Scopes

• aisp
• cbpii
• extended_transaction_history

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}/o-confirmation

paymentRequestOConfirmation

Résumé

Confirmation of a payment request or a modification request using an OAUTH2 Authorization code grant (PISP)

Description

The PISP confirms one of the following requests or modifications:
– payment request on behalf of a merchant
– transfer request on behalf of the account’s owner
– standing-order request on behalf of the account’s owner
The ASPSP answers with a status of the relevant request and the subsequent Credit Transfer. – The TPP has been registered by the Registration Authority for the PISP role
– The TPP was provided with an OAUTH2 « Client Credential » access token by the ASPSP (cf. § 3.4.2).
– The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3) – The ASPSP has answered with a location link to the saved Payment Request (cf. § 4.5.4) – The TPP has retrieved the saved request in order to get the relevant resource Ids (cf. § 4.6).
– The PSU has been authenticated by the ASPSP through an OAUTH2 authorization code grant flow (REDIRECT approach) and the PISP got the relevant token
– The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its « OAUTH2 Authorization Code » access token Once the PSU has been authenticated through an OAUTH2 authorization code grant flow (REDIRECT approach), it is the due to the PISP to confirm the Request to the ASPSP in order to complete the process flow.
The ASPSP must wait for confirmation before executing the subsequent Credit Tranfer.

Scopes

• pisp
• aisp
• extended_transaction_history
• cbpii

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.4.2/trusted-beneficiaries

trustedBeneficiaries

Résumé

Retrieval of the trusted beneficiaries list (AISP)

Description

This call returns all trusted beneficiaries that have been set by the PSU.
Those beneficiaries can benefit from an SCA exemption during payment initiation.
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.
– The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 « Authorization Code » or « Resource Owner Password » access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 « Authorization Code » or « Resource Owner Password » access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
The AISP asks for the trusted beneficiaries list.
The ASPSP answers with a list of beneficiary details structure.

Scopes

• cbpii
• aisp
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

Vérifiez la disponibilité des fonds

Ce service permet de vérifier la disponibilité des fonds pour le compte de notre client pour un montant donné d’une transaction.

Prérequis

Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité, d’avoir récupéré le jeton d’accès OAUTH2 (voir le cas d’usage « Récupérez votre jeton ») et de fournir les paramètres du body.

Requête

POST /funds-confirmations

Paramètres obligatoires du body requis pour l’appel de ce service

• paymentCoverageRequestId : Identifiant de la requête de paiement

• instructedAmount : La structure comprenant le montant renseigné ainsi que la devise
  • currency : Devise du montant renseigné
  • amount : Montant qui permettra de déterminer si les fonds sont disponibles

• accountId : Identifiant unique pour le compte renseigné
  • iban : Numéro de compte bancaire international (IBAN)

Réponse

Le résultat retourné reprendra les informations de la requête ainsi que la réponse concernant la disponibilité des fonds sous la forme d’un booléen.

Un lien self sera également présent pour revenir à la page obtenue juste après exécution de la requête .

Exemple

Requête

POST /v1/funds-confirmations

Body
{

« paymentCoverageRequestId » : « MyCoverage123456 »,

« instructedAmount » : {

« currency » : « EUR »,

« amount » : « 12345 » },

« accountId » : { « iban » : « YY13RDHN98392489481620896668799742 » }

}

}

Résultat

Status code : 200

Body
{

« request » : {

« paymentCoverageRequestId » : « MyCoverage123456 »,

« instructedAmount » : {

« currency » : « EUR »,

« amount » : « 12345 » },

« accountId » : {« iban » : « YY13RDHN98392489481620896668799742 » }

},

« result » : true,

« _links » : {

« self » : {

« href » : « v1/funds-confirmations »

}

}

}

Historique des versions

Cette API REST est conforme à la spécification interbancaire française STET (https://www.stet.eu/en/psd2/) afin de répondre aux exigences réglementaires de la DSP2. Voir la section « limitations » pour prendre connaissance des limitations fonctionnelles.

Pour rappel :

• les textes de la directive de paiement numéro 2 (DSP2, référence UE 2015/2366 du 25/11/2015) sont rentrés en application le 13 janvier 2018 : http://eur-lex.europa.eu/legal-content/FR/TXT/?uri=CELEX:32015L2366

• ils ont été complétés par les normes techniques de réglementation (NTR, règlement délégué UE 2018/389) relatives à l’authentification forte du client et à des normes ouvertes communes et sécurisées de communication dont la date d’application se situe au 14 septembre 2019. Ces normes sont les RTS (Rules Technical Standards) : https://eur-lex.europa.eu/legal-content/FR/TXT/?toc=OJ%3AL%3A2018%3A069%3ATOC&uri=uriserv%3AOJ.L_.2018.069.01.0023.01.FRA

En France, l’ordonnance n° 2017-1252 du 9 août 2017 transpose la directive DSP2 dans la partie législative du code monétaire et financier. L’ordonnance est complétée au plan réglementaire par les décrets n° 2017-1313 et n° 2017-1314 du 31 août 2017 et les cinq arrêtés du 31 août 2017.

Planning des évolutions à venir de l’API

Conformément à l’article 30 (5) des RTS, une assistance pour les prestataires PSP tiers est mise à disposition. Ce support est accessible via le formulaire sur ce portail BPCE API, ou via https://www.api.89c3.com/fr/nous-contacter. Les réponses se font pendant les heures de travail ouvrées.

Le principe général du support est schématisé ci-dessous en prenant en compte les délais réglementaires prévus à l’article 30 (4) des RTS :

Versionning de l’API

Vous pouvez consulter l’assistant virtuel au sujet des textes de la norme STET.

Evolutions importantes apportées depuis la dernière version livrée

Roadmap

Politique de décommissionnement des versions de l’API

La politique du décommissionnement (= arrêt d’une version d’une API sur les environnements de production et sandbox) est fonction du cycle de vie des API, et il est prévu une phase de tuilage entre deux versions majeures d’API comme indiqué dans le schéma ci-dessous :

La communication du décommissionnement d’une version N se fera à la date de déploiement de la version N+1. Le canal de communication privilégié est le portail BPCE API dans la partie « Roadmap » de l’API impactée. Une communication via courriel vers les correspondants des prestataires enrôlés sur le portail BPCE API pourra venir compléter ce dispositif.

Planning des évolutions fonctionnelles à venir de l’API

Cette API fait l’objet d’améliorations et d’évolutions continues. L’article 30 (4) des RTS précise que des changements significatifs de l’API peuvent intervenir sans délai. Nous appliquons cette clause dans les cas suivants :

• problème bloquant impactant de façon généralisée au moins l’un des segments de clients majeur (particuliers, professionnels, entreprises)
• problème de sécurité
• évolutions demandées par les autorités nationales compétentes pour répondre à la trajectoire réglementaire

Retrouvez ci-dessous les éléments de notre trajectoire prévisionnelle :

(*) Fonctionnalités Principales :

• Obtention de l’information demandée sous forme OUI/NON
• Pas de blocage des fonds par le teneur de compte
• Pas de différence entre les versions STET V1.4.0 et V1.4.2

Limitations

Limitations fonctionnelles

Les limitations de cette API DSP2 sont les suivantes :

• Ne s’applique qu’aux comptes de paiements en euros, éligibles (non bloqué ou sous séquestre) et accessibles en ligne (cf. texte de la Directive DSP2)

• Ne couvre que les segments des particuliers (compte de dépôt) et professionnels/entrepreneurs individuels (compte courant)

• N’utilise que le mode d’authentification par redirection (Authentification Forte du client demandée et gérée via la banque)

• Ne permet l’accès que via l’IBAN du compte de paiement (et non via l’identifiant de votre instrument de paiement)

NB : le TPP n’a pas la possibilité de fournir à l’ASPSP les données de sécurité personnalisées du client à des fins d’authentification, et donc, seuls les écrans de redirection et d’authentification forte (SCA) de l’ASPSP doivent être utilisés (l’encapsulage de ces écrans par le TPP est interdit au regard des articles PSD2 #97.5 et RTS #31)

Accès aux données de production

Pour accéder aux données réelles, veuillez utiliser auparavant notre API « Register ».

Comme pour les autres API DSP2, le code établissement vous permettra d’adresser le bon référentiel client via un point d’accès au format :

www.<codetab>.live.api.89c3.com

Exemples :

• STET V1.4.0 POST https://www.30258.live.api.89c3.com/stet/psd2/v1/funds-confirmations ( /!\ scope = piisp )

• STET V1.4.2 POST https://www.30258.live.api.89c3.com/stet/psd2/v1.4.2/funds-confirmations ( /!\ scope = cbpii )

Eligibilité

Les ressources de cette API ne peuvent être consommées que par des PSP ayant le rôle « CBPII » ou « PIISP » suivant la version STET utilisée. Ce statut est délivré par les autorités financières du pays dans lequel la demande est effectuée ; en France il s’agit de l’Autorité de Contrôle Prudentiel et de Résolution (ACPR), liée à la Banque de France.

L’obtention et la conservation d’un agrément relèvent de procédures rigoureuses afin d’apporter des garanties fortes aux utilisateurs des services de paiements, les formulaires étant disponibles sur le site de l’ACPR https://acpr.banque-france.fr/autoriser/procedures-secteur-banque/tous-les-formulaires.

Une fois l’agrément donné, le format de cet identifiant (Organisation Identifier = OID) fourni par l’autorité compétente est PSDXX-YYYYYYYY-ZZZZZZZZ :

XX =>code ISO 3166 du pays de l’autorité compétente hyphen-minus « – » (0x2D (ASCII), U+002D (UTF-8))YYYYYYYY => 2-8 caractères du l’identifiant de l’autorité compétente (A-Z, pas de séparateur)hyphen-minus « – » (0x2D (ASCII), U+002D (UTF-8))ZZZZZZZZ => identifiant du PSP spécifié par l’autorité nationale compétente (sans restriction sur le nombre – ou sur le type – de caractère utilisé)

Cet identifiant OID est important à 2 titres :

• il servira à vous identifier lors des appels dans les requêtes des API STET (via le paramètre « client_id »)

• il devra être présent dans les certificats eIDAS que vous fournirez au teneur de compte (voir ci-dessous)

De plus, vous devez disposer de certificats délivrés par une autorité de certification reconnue (Qualified Certification Service Providers – QTSP: https://webgate.ec.europa.eu/tl-browser/#/) conformes au règlement eIDAS (electronic IDentification And trust Services: https://www.ssi.gouv.fr/entreprise/reglementation/confiance-numerique/le-reglement-eidas/) et respectant la norme ETSI (https://www.etsi.org/deliver/etsi_ts/119400_119499/119495/01.02.01_60/ts_119495v010201p.pdf).

Afin de consommer les API DSP2 proposées sur le portail du groupe BPCE, vous aurez à nous transmettre vos certificats QWAC et QSEALC :

• de production pour le fonctionnement de l’assemblage en sandbox (si disponible pour cet ASPSP)

• de production lors des appels sur notre passerelle BPCE API Live

NB : En cas de renouvellement de certificat, et si l’autorité de certification (QTSP) est différente (ou c’est la même entreprise QTSP mais qui utilise des clés racine différentes), le TPP doit avertir le support API disponible via ce site de 2 mois avant à toutes fins de vérifier que les élements de la nouvelle AC sont bien chargés sur nos infrastuctures.

Un identifiant keyID devra aussi être fourni dans un format conforme à la spécification STET intégrant une empreinte SHA256 après le caractère « _ » char, voir exemple STET V1.4.2 / Documentation Part 3: Interaction Examples / section 6. AISP Use cases / Signature : keyId=https://path.to/myQsealCertificate_612b4c7d103074b29e4c1ece1ef40bc575c0a87e.

Seules les clés publiques au format .pem sont nécessaires. Des contrôles sur les données des certificats seront effectués à partir des registres Français (REGAFI : https://www.regafi.fr) et Européen (ABE ou EBA : https://euclid.eba.europa.eu/register/pir/disclaimer).

Vous pouvez également consulter l’assistant virtuel au sujet du principe de l’agrément.