![](https://developer.bpce.fr/app/uploads/2023/04/Acces-aux-comptes-mobile.png)
![](https://developer.bpce.fr/app/uploads/2023/04/Acces-aux-comptes-desktop01.png)
BTP Banque – Account Information – (STET Standard V1.6.2)
How to aggregate data ?
A customer having different accounts in various banks is willing to agregate his data.
Using this API “Account information” setup by banks (ASPSP), you can ask for real-time data authorized by the customer without asking for online banking credentials.
The API resources can only be consumed if you have obtained the Account Information Services Provider (“AISP”) role status. This prerequisite is described in section “Eligibility“.
Once done, the overall process is as follows :
The customer agreed to use your service. He needs to select his ASPSP through your interface.
During the first set of data exchanges, you will request for an authorization token (and a refresh one). For this AISP role, you need these tokens BEFORE consuming API resources. These tokens are issued by the ASPSP AFTER an identification and authorization process of the bank accound holder.
The ASPSP will :
- check your certificates and on-going agreement delivered by the Comptent Authority
- identify and authorize the customer using the “redirect” mode in order to issue the tokens.
If the above access is granted by the customer, you can then get these OAUTH2 tokens thru secure exchanges (see use case “Get your token“).
Whenever you present this token to the BPCE API gateway, you will be able to consume this API resources in order to :
- request for the list of eligible accounts (see use case “List accounts“)
- forward customer’s consent to the ASPSP (see use case “Forward customer’s consent“)
- securely access to granted customer’s data (see use case “Access to data“)
If the regulated 180-day token validity period expires, this process needs to be started again (see use case “Refresh your token“)
Note : any ASPSP can refuse the access to customer’s data for any justified reason (non compliant API call, blocked account, …).
Get your token
Principle
Access to PSD2 API features is granted by the bank with an authorization token (or access token) issued using OAUTH2 standardized process.
How it works
See also STET specifications
1- The customer (PSU) provides the identity of the bank which holds his accounts (ASPSP) to the TPP
2- The TPP initiates an OAUTH2 access token request sequence by redirecting the customer to the ASPSP’s authorization infrastructure using GET /authorize
See also STET specifications
3- ASPSP will :
- Identify and authenticate the PSU
- Check your role and validity of your eIDAS certificates and agreement
4- Once checks are done and correct, ASPS will redirect the PSU to your site using “call-back” URL given in the GET /authorize and to ASPSP for the Go Live process.
You will find in the response of this request a one-time-token with a short life period.
5- You can then call the ASPSP in order to request the OAUTH2 token (and refresh one) using POST /token with previously received data (incl’d the one-time-token).
Note : these /token requests for getting the Authorization Code flow shall be sent WITHOUT the « scope » parameter.
See also STET specifications
6- ASPSP will :
- Check your role and validity of your eIDAS certificates and agreement
- Checks the direct or indirect matching between the Authorization Number within the eIDAS certificate and the [client_id] value
7- Once checks are done and correct, ASPSP returns a response HTTP200 (OK) with data including the access token.
See also STET specifications
8- As soon as you get the OAUTH2 access token (and a 180-day valid refresh token) issued by the bank, you can use it for each API request within the “Authorization” header, prefixed by the token type “Bearer”.
The [client_id] that is linked to the access token must directly or indirectly match with the Authorisation Number that is located within the TPP’s eIDAS certificate (QWAC).
If the access token is expired, the request will be rejected with HTTP401 with an error equal to “invalid_token”.
The request can be replayed once the access token has been refreshed suing the use case “Refresh your token“.
If your refresh token is about to expire, you will have to perform again all this process, meaning also redirect to ASPSP for customer’s strong autentication (PSU SCA).
For more details, see also OAUTH 2.0 Authorization Framework : https://tools.ietf.org/html/rfc6749#section-4.1
Example
You can find an example of this request in section “Test our API” and then “Sandbox“.
Access to data
In order to query an API, the API version is included in the URI such as : /stet/psd2/v1.6.2/accounts.
The features are described hereafter only from a functional standpoint. The technical aspects are included in the section « Technical use cases ». You also need to be familiar with PSD2 terminology. You may also use the Frequently Asked Questions (FAQ) or our the virtual assistant .
As a reminder, this API is designed to give access to payment accounts (and to a predefined set of data) granted by the customer :
- balance
- and/or transactions history + details if available
- and/or connected customer
- and/or overdraft
Some of these services may have some contraints or may not be available if not present in the online banking environment.
In sandbox assembly mode, access to tests data can be done thru the endpoint www.<codetab>.sandbox.api.89C3.com (see use case « Test our API »).
In production, acces to live data can be done through the endpoint www.<codetab>.live.api.89C3.com (see use case « Limits»).
Get the list of eligible payment accounts
Description
This first call allows to get the list of eligible payment accounts when the user of payment services (PSU) is using services from a third party provider (TPP AISP) connected to the bank account holder (ASPSP).
Prerequisites
- TPP has an agreement for the AISP role from any european competent authority
- TPP and PSU have service contract
- An OAUTH2 access token has been delivered to the TPP by the ASPSP
- TPP and ASPSP have been performed a mutual authentication
- TPP has delivered his OAUTH2 access token to be able to consume the API resources
Transaction flow
TPP is interacting with the customer thru its interfaces. TPP sends a GET request to ASPSP infrastructure to get this list of accounts, which returns the eligible payment accounts.
Customer consent
Description
This second request is mandated by the ASPSP : TPP has requested the customer to give his consent on the accounts he wants to use (ans which data).
This information (list of authorized accounts and data) needs to be sent back by the TPP to the the bank (ASPSP) for recording this customer consent. This “consent” record is linked only to a given PSU + given TPP AISP + given authorized payment account(s) + given authorized data for each account. The ASPSP will verifiy each TPP access request to the accounts vs. this record.
This consent can be modiifed at any time by calling again this service.
Prerequisites
TPP has requested the list of accounts for the first time.
PSU give his consent to AISP.
Transaction flow
TPP AISP forward these authorized data to the bank (ASPS) using a PUT request.
Get balance
Description
This call allows to get the accountable balance (“CLBD” in STET specifications).
Prerequisites
TPP has requested the list of accounts and sent PSU consent to ASPSP.
Transaction flow
AISP requests the ASPSP to send back the balance of one of the authorized accounts.
Get transactions history
Description
This call allows to get the 90-day deep transactions history.
Prerequisites
TPP has requested the list of accounts and sent PSU consent to ASPSP.
Transaction flow
AISP requests the ASPSP to send the transaction history with some criteria.
Get PSU identity
Description
This call allows to get the connected customer identity.
Prerequisites
TPP has received PSU consent of this data and sent it to ASPSP.
Transaction flow
AISP requests the ASPSP to send PSU identity data.
Get PSU overdraft
Description
This call allows to get the account overdraft.
Prerequisites
TPP has requested the list of accounts and sent PSU consent to ASPSP.
Transaction flow
AISP requests the ASPSP to send overdraft data.
Refresh your token
Principle
The refresh token issued by the bank ASPSP is valid up to 180 days and needs to be renewed before it expires. Please also note that :
- Authorization and refresh tokens can be revoked at any moment
- If the Authorization token is revoked, then the refresh one is automatically revoked (and the other way round)
- The access token has a shorter life cycle (10 to 15 minutes) on a standalone device
How it works ?
1. You request for a refresh token using POST /token
2. ASPSP :
- Identifies and authenticates the TPP through the presented eIDAS certificate (QWAC)
- Checks the direct or indirect matching between the Authorization Number within the eIDAS certificate and the [client_id] value
- Controls last PSU SCA date (< 180 days presently)
3. If correct, ASPSP then answers through a HTTP200 (OK) that embeds a new autorization token and refresh token that can replace the previous one. You need to store safely these tokens.
4. ASPSP de facto revokes the previous refresh token :
- After timeout of the by-law specified delay between two SCAs
- After timeout of the ASPSP specified delay based on internal rules if any
- After reject of a request for insufficient scope in order to allow the AISP to request another token with the desired scope
- On request of a PSU wanting to revoke the TPP access on his/her account data
Please also note that, as a TPP, you are able to ask for the revocation of the refresh token through a POST /revoke request.
Revoke the token
A revoke process of the refresh access token (before its expiration @180 days) is possible, see STET specifications.
Example
You can find an example of this request in the section”Test our API” and then “Sandbox“.
How to use the fallback mode ?
Principle
In order to comply with PSD2 regulations, banks available on this BPCE API developer portal have setup contingency measures in case of unplanned unavailability of the dedicated API interface.
The principle of this « fallback » solution is explained below:
This fallback mechanism meets PSD2 regulatory requirements (article 33/RTS). It can be used with the same conditions and prerequisites applicable for the dedicated API interface which are specified in the “Eligibility” use case.
Roadmap
Please do find below our estimated roadmap :
Version | Features | Sandbox
Deployment BPCE API Dev Portal & Sandbox |
Live
Deployment BPCE Live API Gateway |
v1.0 |
|
Not applicable | September 2019 |
(*) Main features :
- Use the same API dedicated interface endpoint. The list of our banking institutions and the possible values of <bkcode> are specified in the “Limitations” use case
- A parameter (header ‘fallback:1’ present or absent) managed directly by the TPP allows do differentiate any « Fallback » request from dedicated interface PSD2 API requests
- Use of same TPP eIDAS certificate (QWAC) to be presented for mutual TLS authentication
- Use the same PSU authentication procedure and means for accessing online banking services
- This fallback solution is always active, even so the dedicated interface API must be used systematically in first priority. Its usage is subject to strict conditions as described in Article 33 of RTS, and can’t be used as the main access for PSD2 features. It will be monitored as such and every abuse will be automatically reported to our national competent authority
Example
- If PSD2 API are not available due to unplanned unavailability or systems breakdown (see RTS Art. 33), TPP should use the following request qith <codetab>=17515 as an example :
POST https://www.17515.live.api.89c3.com/stet/psd2/oauth/token
with :
- its live eIDAS QWAC certificate
- fallback:”1″ parameter in the header
POST /stet/psd2/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
X-Request-ID: 1234
fallback: 1
User-Agent: PostmanRuntime/7.16.3
Accept: */*
Cache-Control: no-cache
Host: www.17515.live.api.caisse-epargne.fr
Accept-Encoding: gzip, deflate
Content-Length: 67
Connection: keep-alive
client_id=PSDFR-ACPR-12345&grant_type=client_credentials&scope=aisp
2. If all checks are successful, the TPP will receive in the header of the response with url online (allowing to access banking login web page) as well as the JWT token to be used also in the rediction process.
HTTP/1.1 302 Found
Date: Tue, 25 May 2021 21:46:59 GMT
Content-Length: 870
Connection: close
Content-Type: text/html; charset=iso-8859-1
</head><body>
<h1>Found</h1>
<p>The document has moved <a >here</a>.</p>
</body></html>
3. Once redirected, the TPP can then apply its proprietary login process using PSU credentials.
For more details about POST request, see STET specifications
Please note the following constraints which apply on this fallback mechanism :
Please note the following constraints which apply on this fallback mechanism :
- No re-use of the API dedicated interface context, neither any of 180-day validity access token generated for AISP role
- Only online internet banking features are used as a reference (excl’d mobile banking features) and are accessible thru the fallback mode. As an example, online banking doesn’t propose any e-commerce transactions to customers. PISP could NOT propose this feature in fallback mode
- The user of payment services (PSU) must be connected to PSP app. So no AISP batch process is possible
- PSD2 also imposes a reinforcement of strong customer authentication (SCA) for accessing direct online banking services. Therefore fallback mechanism leverages on reinforced PSU online banking authentication procedures and means such as (non exhaustive list) :
- Soft token Secur’Pass on smartphone
- Password + OTP SMS
- Physical token (corporate market)
Trigger App2App feature
Introduction
This service allows you to activate automatically (without PSU action) the banking app on PSU smartphone for identification and authentification process.
Prerequisites
The PSU has to load and to use at leat once the latest retail banking mobile app (V6.4.0 and higher) available on Android and Apple app stores.
Note : PRO & ENT customer segments are not yet activated
The callback universal link (same principe as url callback) shall be definied in advance by the TPP :
- if this link/url already exists on our BPCE API gateways, there is nothing else to do
- otherwise the TPP shall declare it using our API Register
Our “Universal links” links have been declared on iOS & Android platforms. It is not worthwhile to access to them e. g. using https://www.<codetab>.live.api.caisse-epargne.fr/89C3api/accreditation/v2/.well-known/apple-app-site-association which sends back an error code.
Request
PSU banking app activation can be achieved in live production using a current STET API request (initiated by the TPP app on the same smartphone device) with the following endpoints :
Brand | App2App endpoint |
![]() |
www.40978.live.api.palatine.fr/stet/psd2/oauth/authorize |
![]() |
.live.api.banquepopulaire.fr/stet/psd2/oauth/authorize” >www.<codetab>.live.api.banquepopulaire.fr/stet/psd2/oauth/authorize
(see <codetab> values on Banque Populaire API product data sheet) |
![]() |
www.10548.live.api.banque-de-savoie.fr/stet/psd2/oauth/authorize |
![]() |
www.<codetab>.live.api.caisse-epargne.fr/stet/psd2/oauth/authorize
(see <codetab> values on Caisse d’Epargne API product data sheet) |
![]() |
www.12579.live.api.banquebcp.fr/stet/psd2/oauth/authorize |
![]() |
www.42559.live.api.credit-cooperatif.coop/stet/psd2/oauth/authorize |
![]() |
www.30258.live.api.btp-banque.fr/stet/psd2/oauth/authorize |
![]() |
www.18919.live.api.natixis.com/stet/psd2/oauth/authorize |
Otherwise, a webview will be displayed on PSU smartphone web browser if :
- the banking app is not present on PSU device nor App2App compliant (not the latest version uploaded, see prerequisites)
or
- the other endpoint format is used www.<codetab>.live.api.89c3.com/stet/psd2/oauth/authorize (can be used as a backup in case of App2App problem)
Regulatory publications
Period | Document |
Availability of DSP2 APIs to date | Load the document |
Statistics Q1 2024 | Load the document |
Statistics Q4 2023 | Load the document |
Statistics Q3 2023 | Load the document |
Statistics Q2 2023 | Load the document |
Statistics Q1 2023 | Load the document |
Statistics Q4 2022 | Load the document |
Statistics Q3 2022 | Load the document |
Statistics Q2 2022 | Load the document |
Statistics Q1 2022 | Load the document |
Statistics Q4 2021 | Load the document |
Statistics Q3 2021 | Load the document |
Statistics Q2 2021 | Load the document |
Statistics Q1 2021 | Load the document |
Statistics Q4 2020 | Load the document |
Statistics Q3 2020 | Load the document |
Statistics Q2 2020 | Load the document |
Statistics Q1 2020 | Load the document |
Catégories
/stet/psd2/v1.6.2/accounts/{accountResourceId}/balances
accountsBalances
Abstarct
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
Prerequisites
– The TPP was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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 should provide at least one balance on the account. – For cash account, this balance should be the accounting balance (CACC) – For card transactions account, the accounting balance is meaningless and must be replaced by an other type of balance (OTHR).
– Case of no registered transaction on the account, this balance will have an amount equal to zero.
– 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
- pisp
- aisp
- cbpii
- extended_transaction_history
Parameters
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return code
200 | The ASPSP answers with a list of account balances |
204 | No content. |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Availables authentification
OAuth 2.0
/stet/psd2/v1.6.2/accounts
accounts
Abstract
Retrieval of the PSU accounts (AISP)
Description
Description
This call returns all payment accounts that are relevant for 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 was registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that was 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
- pisp
- cbpii
- aisp
- extended_transaction_history
Parameters
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return code
200 | The ASPSP return a PSU context – listing the accounts that were made available to the AISP by the PSU and, – for each of these accounts, the further transactions that were enabled by the PSU through HYPERMEDIA links. |
204 | No content. |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/accounts/{accountResourceId}/overdrafts
accountsOverdrafts
Abstract
Retrieval of an account overdraft (AISP)
Description
Description
This call returns the overdrafts that can be used 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
Prerequisites
– The TPP was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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.
The ASPSP answers by the overdraft that can be applied.
Scopes
- pisp
- extended_transaction_history
- cbpii
- aisp
Parameters
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return code
200 | Overdraft response |
204 | No content. |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/accounts/{accountResourceId}/owners
accountsOwners
Abstract
Retrieval of an account owners (AISP)
Description
Description
This call returns the owners identities for a given PSU account that is specified by the AISP through an account resource identification.
This call cannot be used when the account is owned by a legal entity where the identity of this entity is directly available in the account structure (field [company]).
Prerequisites
– The TPP was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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.
The ASPSP answers by the identities of the account owners.
Scopes
- extended_transaction_history
- cbpii
- pisp
- aisp
Parameters
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return code
200 | Account owners identities response |
204 | No content. |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/accounts/{accountResourceId}/transactions/{transactionResourceId}/details
accountsTransactionsDetails
Abstract
Retrieval of transaction details (AISP)
Description
### Description
This call returns the details of a transaction from a given PSU account.
The AISP has to specified
– the account through an account resource identification
– the transaction through a transaction resource identifcation
### Prerequisites
– The TPP was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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 and the transactions from one given account
– A transaction includes a “details” hyperlink which indicates that detailed information is available for this transaction.
### Business flow
The AISP requests the ASPSP on one of the transactions.
The ASPSP answers by the details on this transaction.
Scopes
- pisp
- cbpii
- aisp
- extended_transaction_history
Parameters
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
transactionResourceId (required) | string path Identification of transaction resource to fetch |
dateFrom | string query Inclusive minimal imputation date of the transactions. Transactions having an imputation date equal to this parameter are included within the result. |
dateTo | string query Exclusive maximal imputation date of the transactions. Transactions having an imputation date equal to this parameter are not included within the result. |
dateType | string query This parameter specifies the type of date on which [dateFrom] and [dateTo] apply. If not provided, the ASPSP will use its own default date type as specified in its implementation documentation. The implementation documentation must also specify which date types are supported. |
entryReferenceFrom | string query Specifies the value on which the result has to be computed. Only the transaction having a technical identification greater than this value must be included within the result |
entryReferenceto | string query Specifies the value on which the result has to be computed. Only the transaction having a technical identification less than or equal to this value must be included within the result |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return code
200 | Complete transactions response |
204 | No content. |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/accounts/{accountResourceId}/transactions
accountsTransactions
Abstract
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 was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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.
– Case of no registered transaction on the account, this result will be an empty list.
The default transaction set, in the absence of filter query parameter, has to be specified and documented by the implementation.
The sort order of transaction might be specific to each ASPSP, due to each Information System constraints.
Scopes
- extended_transaction_history
- cbpii
- aisp
- pisp
Parameters
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
dateFrom | string query Inclusive minimal imputation date of the transactions. Transactions having an imputation date equal to this parameter are included within the result. |
dateTo | string query Exclusive maximal imputation date of the transactions. Transactions having an imputation date equal to this parameter are not included within the result. |
dateType | string query This parameter specifies the type of date on which [dateFrom] and [dateTo] apply. If not provided, the ASPSP will use its own default date type as specified in its implementation documentation. The implementation documentation must also specify which date types are supported. |
entryReferenceFrom | string query Specifies the value on which the result has to be computed. Only the transaction having a technical identification greater than this value must be included within the result |
entryReferenceto | string query Specifies the value on which the result has to be computed. Only the transaction having a technical identification less than or equal to this value must be included within the result |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return code
200 | Complete transactions response |
204 | No content. |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/consents
consents
Abstract
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 was registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that was 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
- cbpii
- extended_transaction_history
- aisp
- pisp
Parameters
Authorization (required) | string header Access token to be passed as a header |
access (required) | Access body List of consents granted to the AISP by the PSU. |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Return code
201 | Created |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
501 | Not Implemented. This code should be used when the entry point is implemented but cannot provide a result, given the context. When the entry point is not implemented at all, HTTP400 will be returned. |
503 | Service unavailable. |
Input
application/json
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/end-user-identity
endUserIdentity
Abstract
Retrieval of the identity of the end-user (AISP)
Description
Description
This call returns the identity of the PSU (end-user).
Prerequisites
– The TPP was registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that was 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 identity of the PSU. The ASPSP answers with the identity, i.e. first and last names of the end-user.
Scopes
- aisp
- pisp
- cbpii
- extended_transaction_history
Parameters
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Return code
200 | The ASPSP returns the identity of the PSU |
204 | No content. |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
429 | Too many requests. |
500 | Internal server error. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/trusted-beneficiaries
trustedBeneficiaries
Abstract
Retrieval of the trusted beneficiaries list (AISP)
Description
Description
This call returns all trusted beneficiaries that were 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 was registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that was 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
- cbpii
- aisp
- extended_transaction_history
- pisp
Parameters
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return code
200 | The ASPSP returns the list of whitelisted beneficiaries |
204 | No content. |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
429 | Too many requests. |
500 | Internal server error. |
501 | Not Implemented. This code should be used when the entry point is implemented but cannot provide a result, given the context. When the entry point is not implemented at all, HTTP400 will be returned. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
Catégories
-
Technical use cases
-
Test our API
Get accounts list
Principle
Using this service, you can get access various data from a payment account authorized by the customer :
- list all eligible online accessible payment accounts
- retrieve accounting balance
- get URI for the GET /end-user-identity method
- get URI for GET /balances, GET /transactions, GET /details & GET /overdrafts methods
Access to this method is limited to a maximum of 4 batch per day for a given TPP + ASPSP + account + PSU (except if the PSU is connected and has requested this operation).
Prerequisites
In order to proceed, TPP needs to fulfill all eligibility criteria and to present a valid OAUTH2 Authorization token (see use case “Get your token“).
Request
Method “GET /accounts”
See also STET specifications
Returned result
IF YOU USE THIS METHOD FOR THE FIRST TIME
(therefore if you didn’t send previously any information using PUT /consents, OR if all granted accounts have not been revoked using PUT /consents – see use case “Forward customer’s consent“) :
This call allows you to list all eligible online accessible authorized payment accounts (incl’s new ones) from our customer (without balances, URI or ressourceID) for the following methods :
- GET /balances
- GET /transactions & GET /details
- GET /overdrafts
IF YOU HAVE ALREADY FORWARDED AT LEAST ONE CONSENT FROM THE CUSTOMER USING PUT /CONSENTS
(therefore if you have used previously PUT /consents request, OR if all granted accounts have not been revoked using PUT /consents – see use case “Forward customer’s consent“) : this call allows you to retrieve all eligible online accessible authorized payment account with the following additional data :
- Accounting balance if this account is flagged in the “balances” parameter in PUT /consents method
- URI for the GET /balances method if this account is flagged in the “balances” parameter in PUT /consents
- URI for the GET /transactions & GET /details (if available)methods if this account is flagged in the “transactions” parameter in PUT /consents
- URI for the GET /overdrafts method if this account is flagged in the “overdrafts” parameter in PUT /consents
Note :The « currency » paramater is now inserted in « accountId » field
Example
You can find an example of this request in section “Test our API” and then “Use our sandbox“.
Acceptance tests
The purpose of these tests is to ensure that the API complies with the STET standard. They should be validated before any application deployment.
Description | Test data |
Get all PSU payment accounts | PSU Persona : CLAIRE
PSU context = BY-AISP scope OAuth2 = aisp Result: message HTTP 200 => OK with 2 accounts returned |
HTTP request with non autorized access token for this resource (wrong scope)
=> check if HTTP 403 is returned (access refused) |
PSU Persona : LEA
PSU context = BY-AISP scope OAuth2 <> aisp Result : Error message HTTP 403 returned |
Use a non authorized request (POST)
=> check if HTTP 405 is returned |
PSU Persona : LEA
PSU context = BY-AISP scope OAuth2 = aisp Result : Error message HTTP 405 returned |
Forward customer's consent
Introduction
This service is mandatory as required by Caisse d’Epargne ASPSP as part of the “Mixed” model.
Prerequisites
It is necessary to fulfill the eligibility prerequisites and to have retrieved the OAUTH2 access token (see the “Overview“> “Recover your token” section).
You can retrieve the list of the customer’s eligible payment accounts after calling the GET /accounts request for the first time: you will find the IBAN associated with each account, ie “accountId”: {“iban”: ” “}.
However, if you already know the IBAN (s) for the customer’s payment accounts, you can send them to us directly via the PUT / consents method.
WARNING: as long as you have not communicated to the account keeper (ASPSP) at least one account authorized with the PUT /consents method, or if no account is authorized, this GET /accounts method will not return the information requested but only the list of all current accounts included new ones (principle of “AISP mixed consent”).
Request
Method “PUT /consents”
See also STET specification
The PSU specifies to the AISP which of his/her accounts will be granted and which data should be available : it gives his consent and included four access types (or operation types) :
- balances : access to one or many PSU accounts balance report
- transactions : access to one or many PSU accounts transactions history and details (if available)
- psuIdentity : access to connected PSU identity (name & surname for retail customer, ot corporate ID for a company)
- overdrafts : access to PSU accounts overdraft
Note : the following methods are NOT supported
- GET /trustedBeneficiaries : whatever value is used (True/False), it won’t be taken into account
- GET /owners : whatever value is used, it won’t be taken into account
The AISP forwards details of PSU consent to the ASPSP through this call.
Each new API request calls the ASPSP consent service, for one given PSU, replaces any prior consent that was previously sent by the AISP.
Furthermore, upon the PSU’s request, the consent may be updated subsequently for an operation type : for example, access to transactions can be revoked while access to balances stay active :
- If no accounts is transmitted with PUT /consents method, and if a consent was given previously for some accounts using this method, then it means that the customer is revoking all his accounts
- If no accounts is granted, or if the customer has revoked all this consented accounts, the GET /accounts method allows to get all the accounts list (included new ones) but access to related data (balances, transactions) is NOT anymore possible
- In order to get any new account, a PUT /consents with no data is necessary
Example
You can find an example of this request in the section “Test our API” and then “Use our sandbox“. The test data sets are described in the section “Test our API” and then “Test with persona“.
See also STET specification
Acceptance tests
The purpose of these tests is to ensure that the API complies with the STET standard. They should be validated before any application deployment.
Test description | Nature of the test | Data set |
Add / upate the consent of a customer
=> HTTP code 201 is returned |
Mandatory | Persona :
LEA IBANs : FRxxx FRxxx Result : HTTP code 201 is returned |
HTTP request with an access token which is not authorized to access to this resource (incorrect scope)
=> Access to the resource is not allowed (HTTP code 403) |
Mandatory | Persona :
LEA Result : HTTP code 403 is returned |
HTTP request using POST method
=>HTTP code 405 is returned |
Mandatory | Persona :
LEA Result : HTTP code 403 is returned |
Get account balance
Introduction
Using this service, you can get the accounting balance data (“CLBD” in STET) on a payment account granted by the customer.
It follows the return of the list of current accounts for a customer : a resource identifier corresponding to an account must be provided to obtain the corresponding accounting balance.
Access to this method is limited to a maximum of 4 batch per day for one given TPP + ASPSP + account + PSU (except if the PSU is connected and has requested it).
Prerequisites
The TPP has previously retrieved the list of available accounts for the PSU :
- Customer’s IBAN should have been forwarded to ASPSP in the “transactions” list of the PUT /consentsmethod (see use case “Forward customer’s consent“)
- The “accountResourceId” is sent in the GET /accounts response / field “resourceId” for this IBAN
- URI or accessing this method is given using the field “_links”: {“transactions”: {“href”: …}} as a response of the GET /accounts using above “accountResourceId”
Request
Method “GET /accounts/{accountResourceId}/balances”
See also STET specification
Mandated parameter
“accountResourceId” : current account for which you want to retrieve transactions history.
This field corresponds to the field “resourceId” obtained in the GET /accounts request result page.
Example
You can find an example of this request in section “Test our API” and then “Use our sandbox“.
See also STET specification
Acceptance tests
The purpose of these tests is to ensure that the API complies with the STET standard. They should be validated before any application deployment.
Description | Test data |
Get accounting balance
=> Check negative balance |
PSU Persona : LEA
PSU context = BY-AISP scope OAuth2 = aisp Result : message HTTP 200 => OK negative balance returned |
Get accounting balance from an unkown account
=> check if HTTP 404 is returned |
PSU Persona : unkown – CPT30014684067
PSU context = BY-AISP scope OAuth2 = aisp Result : Error message HTTP 404 returned |
HTTP request with non autorized access token for this resource (wrong scope)
=> check if HTTP 403 is returned (access refused) |
PSU Persona : LEA
PSU context = BY-AISP scope OAuth2 < > aisp Result : Error message HTTP 403 returned |
Use a non authorized request (POST)
=> check if HTTP 405 is returned |
Persona : LEA
PSU context = BY-AISP scope OAuth2 = aisp Result : Error message HTTP 405 returned |
Get accounting balance
=> Check null balance |
PSU Persona : CLAIRE
FR7617515900000400358074026 PSU context = BY-AISP scope OAuth2 = aisp Result : message HTTP 200 => OK null balance returned |
Get accounting balance
=> Check positive balance |
Persona : CLAIRE
FR7617515900000800358074006 PSU context = BY-AISP scope OAuth2 = aisp Result : message HTTP 200 => OK positive balance returned |
Get transactions history
Introduction
Using this service, you can get the transactions history data (& details if available) on a payment account granted by the customer.
The type of account is an elligible PDS2 payment account (either a deposit account for individuals, or a current account for professionals and legal entities).
Prerequisites
The TPP has previously retrieved the list of available accounts for the PSU :
- Customer’s IBAN should have been forwarded to ASPSP in the “transactions” list of the PUT /consents method (see use case “Forward customer’s consent“)
- The “accountResourceId” is sent in the GET /accounts response / field “resourceId” for this IBAN
- URI or accessing this method is given using the field “_links”: {“transactions”: {“href”: …}} as a response of the GET /accounts using above “AccountresourceId”
Request
GET /accounts/{accountResourceId}/transactions
GET /accounts/{accountResourceId}/transactions/{transactionResourceId}/details (method to call for each transaction details if they are available)
See also STET specifications
Mandated parameters
“accountResourceId” : current account for which you want to retrieve transactions history.
This field corresponds to the field “resourceId” obtained in the get/accounts request result page.
Optional parameters
- dateFrom : start date to search for transactions (date included)
- dateTo : end date to search for transactions (date NOT included)
- PSU-IP-ADDRESS => to be inserted in the header if the PSU is connected to AISP services
- entryReferenceFrom=> NOT used by this API
- entryReferenceTo => NOT used by this API
- dateType => NOT used by this API
The date format for “dateFrom” & “dateTo” is based on ISO 8601 standards with the three following allowed formats :
- YYYY-MM-DDTHH:MM:SS.SSS or YYYY-MM-DDTHH:MM:SS.SSSZ
- YYYY-MM-DDTHH:MM:SS.SSS+HHMM
- YYYY-MM-DDTHH:MM:SS.SSS+HH:MM
Data Returned
As a reminder :
- BOOK means the transaction was booked and affects the closing booked balance (status used by this API)
- PDNG means the transaction is about to be booked and does not affect the closing booked balance (status NOT used by this API)
- OTHR means the transaction is not booked and does not affect the closing booked balance or the instant balance (status used by this API)
In addition to mandatory data returned, the optional STET data “entryReference” has been added for all transactions knowing that it is :
- unique value in differed debit transaction life cycle (*)
- identical value before & after transaction settlement (from status “OTHR” to “BOOK”)
(*) Note 1 : except for all schedules of a standing order (considered as one transaction overall)
Note 2 : other types of operations (e. g. Paylib) have this data only for “BOOK” status., except for those rejected
The “entryReference” format is different depending on the type of operations :
type | length | example |
differed fund transfer | 25 char | 1310400000123480007081059 |
direct debit | 30 char | 131040000012342014185G10004997 |
differed debit card | 40 char | 1310400000123420140720170000234978987654 |
other operations | 40 char | 131040000012342021-02-08-09.33.46.621234 |
The optional STET data “Bank Transaction Code ” (BTC) has been added ONLY for professional & corporate segement clients (CE Net subscribers or equivalent), e.g. for a SEPA SCT Core :
“bankTransactionCode”: {
“domain”: “PMNT”,
“family”: “RCDT”,
“subFamily”: “ESCT”,
“code”: “05”,
“issuer”: “SI MYSYS – Caisse d’Epargne”
}
Example
You can find an example of this request in section “Test our API” and then “Use our sandbox“.
See also STET specifications
Example
The purpose of these tests is to ensure that the API complies with the STET standard. They should be validated before any application deployment.
Expected Scope = aisp otherwise specified.
Test description | Nature of the test | Data set and Expected Result |
Retrieve all the transactions linked to a PSU’s account
=> Check the presence of transactions |
Mandatory | Persona : GEORGES
Result : return of the current account transaction history |
Retrieve transactions linked to an unknown account
=>HTTP code 404 is returned : {accountId} is invalid |
Mandatory | Persona : LEA
Result : HTTP code 404 is returned |
HTTP request with an access token which is not authorized to access to this resource (incorrect scope = pisp)
=> Check that HTTP code 403 is returned – access to resource not allowed |
Mandatory | Persona : LEA
Result : HTTP code 403 is returned |
HTTP request using POST method
=> Check that HTTP code 405 is returned |
Mandatory | Persona : LEA
Result :HTTP code 405 is returned |
Get transactions list with “dateFrom” parameter
=> Check that the filter is well applied |
Mandatory | Persona : GEORGES
Result : return of a list of transactions after the date given as input parameter |
Get transactions list with “dateTo” parameter
=> Check that the filter is well applied |
Mandatory | Persona : GEORGES
Result :return of a list of transactions before the date given as input parameter, up to the limit of 62 days |
Get transactions list with optional field “entryReference” empty
=> Check that response field “entryReference” is empty |
Mandatory | Persona : GEORGES
Result : return a list of transactions with field “entryReference” empty |
Get transactions list with “dateFrom” and “dateTo” parameters
=> Check that the filter is well applied |
Mandatory | Persona : GEORGES
Result : return of a list of transactions within the dateFrom and dateTo given as input parameters |
Request with “dateFrom” parameter older than 62 days
=> Check that HTTP code 400 is returned – Period out of bound expected |
Mandatory | Persona : LEA
Result : HTTP code 400 is returned |
Request with an invalid “dateFrom” or “dateTo” parameter
=> Check that HTTP code 400 is returned |
Mandatory | Persona : GEORGES
Result : HTTP code 400 is returned |
Get no transactions present in the list
=> Check that HTTP code 204 is returned |
Mandatory | Persona : CLAIRE / account FR7617515900000400358074026
Result : HTTP code 204 is returned |
Get PSU's identity
Introduction
This service allows you to retrieve the connected PSU’s identity who has given you their consent to do so (who is not necessarely the customer having the account).
Prerequisites
To proceed with this request, it is necessary to fulfill the eligibility prerequisites and to have retrieved the OAUTH2 access token (see in the section “Overview” > “Get your access token“).
To get the PSU’s identity, you need :
- The authorization to transmit this identity information to the TPP must have been transmitted to us via the setting to true of the “psuIdentity” attribute of the PUT /consents method and must not have since been revoked (i.e. not cancel and replace via PUT /consents with a “psuIdentity” attribute set to false);
- The URI to access this method is given through the “_links“: {“endUserIdentity”: {“href”: …}} item as a result to the GET /accounts request.
Request
Method GET /end-user-identity
See also STET specifications
Mandatory or optional settings of the body required to call this service
Mandatory settings : PSU-IP-ADDRESS => to inform if the PSU is connected.
Returned result
This call allows you to get the identity of the end customer
A self link will also be available to return to the page obtained after execution of the request.
This method is limited to a maximum of 4 batch calls per calendar day per TPP + ASPSP + account + PSU. However, when the customer is connected to TPP app and requests an access to his current accounts, the number of access is not limited.
Example
You can find an example of this request in section “Test our API” and then “Use our sandbox“.
See also STET specifications
Acceptance tests
These test cases are intended to allow you to perform a minimum of tests to get started with this API and access it from your application.
Description of the test | Data |
User identity recovery | Persona :
Marc – D0999990I0 Prerequisites : scope OAuth2 = aisp Results : HTTP answer 200 => OK |
Recovery of the identity of the user who has not given their consent for this | Persona :
Tech’n Co – D0999993I0 Prerequisites : scope OAuth2 = aisp Results : HTTP answer 403 => access to the ressource denied |
Get account overdraft
Introduction
Using this service, you can get the authorized overdraft on a payment account granted by the customer.
The type of account is an elligible PDS2 payment account (either a deposit account for individuals, or a current account for professionals or corporate entities).
Prerequisites
The TPP has previously retrieved the list of available accounts for the PSU :
-
- Customer’s IBAN should have been forwarded to ASPSP in the “overdrafts” list of the PUT /consents method (see use case “Forward customer’s consent“)
-
- The “accountResourceId” is sent in the GET /accounts response / field “resourceId” for this IBAN
-
- URI or accessing this method is given using the field “_links”: {“transactions”: {“href”: …}} as a response of the GET /accounts using above “AccountresourceId”
Request
GET /accounts/{accountResourceId}/overdrafts
See also STET specifications
Mandated parameters
“accountResourceId” : current account for which you want to retrieve transactions history.
This field corresponds to the field “resourceId” obtained in the get/accounts request result page.
This method can be called in batch mode up to 4 times per day (per TPP per ASPSP per IBAN per PSU). If the PSU is connected to the TPP, no limits apply.
Example
You can find an example of this request in section “Test our API” and then “Use our sandbox“.
See also STET specifications
sandbox
Introduction
This test environment can be used directly via the TPP app.
This ASPSP is on the same IT banking system as Caisse d’Epargne (CE) one. The data returned will be with the same format.
The TPP can use CE data as present in the sanbox.
Version history
STET Compliance
This REST-based API is compliant with the STET specifications developed by the French market initiative (https://www.stet.eu/en/psd2/) in order to comply with PSD2 regulatory requirements. It takes into account functional limitations specific to this retail bank network (see use case ‘Limitations“).
As a reminder :
- payment services directive (PSD2, (UE) 2015/2366 of 25/11/2015) went into force on january 13, 2018 : https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=celex%3A32015L2366
- it is supplemented by regulatory technical standards for strong customer authentication (RTS, Commission Delegated Regulation (EU) No 2018/389) and common and secure open standards of communication that will apply on september14, 2019. These standards are called RTS (Rules Technical Standards) : https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32018R0389
In France, the ordinance n° 2017-1252 of August 9, 2017 implements the PSD2 directive into the regulatory section of the monetary and financial code. This ordinance has been supplemented by two decrees (n° 2017-1313 and n° 2017-1314), and five orders that were published on August 31, 2017.
Our API version | STET standard version |
v1.6.2 | v1.6.2.0 |
You can refer to the STET documentation.
Description of TPP support
According to Article 30 (5) of the RTS, a support for third-party providers is available. This support can be joined via the form on this BPCE API portal (https://developer.bpce.fr/en/support/). Responses are sent during office opening hours (09:00 – 18:00 Central European local Time) even so a 24h/7d monitoring process of our IT systems exists.
Its general principle is shown below, taking into account delays of Article 30 (4) of the RTS :
Release notes
Important changes made since the first release of this documentation was published :
Method(s) | Effective date | Description of the evolution |
All | October 20, 2022 | Alignment on PSD2 API STET v1.6.2.0 |
Roadmap
API deprecation process
According to API product life cycle, an API version can be deprecated (meaning this API is not any more accessible on gateways and sandbox). An overlap period between two major API releases is provided as described below :
The communication around the decommissioning process of a version N will be done at the release date of version N+1 through this portal / “roadmap” section.
Roadmap
This API can evolve. Please note that API modifications can occur out of the three-month regulatory notice period (art. 30 des RTS / paragraphe 4). We apply this in case of :
- urgent functional issue to solve impacting all PSU of at least one major customers segment
- security issue
- evolutions requested by the national competent authority
Please do find below our forecast roadmap :
Our API version | STET Standard version | Features | Deployment date
Dev Portal & Sandbox |
Deployment date
BPCE Live API Gateway |
Deprecation date
BPCE Live API Gateway |
v1.6.2 | v1.6.2.0 | API Version v1 :
API version v1.4.2 = API version v1 +
API version v1.6.2 = API version v1.4.2 +
|
October 20, 2022 | Februray 08, 2023 | To be announced |
Limits
Functional Limits
Limits of this API version
- Apply only to active and eligible online accessible payment accounts in euro currrency (the determining criterion for the purposes of that categorisation lies in the ability to perform daily payment transactions from such an account managed by the central backend IT system, source of data sent back thru APIs)
- Use AISP-mix model (PUT /consents method is mandatory for sending customer consent to ASPSP)
- Use only authentication with redirect mode (Strong Customer Authentication required and handled by the bank which IS NOT an obstacle according to French national competent authority
Note : TPP are NOT allowed to send to ASPSP the PSU credentials, and only ASPSP SCA redirect screens can be used (no embeding process as clarified by European Banking Authority based on articles PSD2 #95.5 & RTS #31)
- Access to the list of trusted beneficiaries using GET /trustedBeneficiaries is NOT available (feature not implemented in ASPSP online banking service interfaces)
- Access to customer account holder identity (first name and last name) using GET /owners is NOT available
- Transaction history data depth is aligned on online banking services (62-day period max for retail cutomers & small professionals/entrepreneurs segments, 90-day period max for large professionals & corporates, limited to 500 operations, no paginations managed by the API in both cases)
- “aisp extended_transaction_history” mode is NOT supported
- Access to payment account is done only using IBAN as main parameter
- There are no rate limits if the PSU-IP-ADDRESS is supplied, otherwise limited to 4 calls (see PSD2 regulations) :
- per calendar day (00h00 – 23h59:59:999)
- per TPP OID
- per ASPSP end point
- per PSU ID
- per IBAN
- per API AIS method (/!\ GET /transactions method with or without “dateFrom” & “dateTo” parameters is considered as one method)
- The optional STET data “dateType” is not supported
- The optional STET data “entryReference” applies only to PART & PRO/EI customer segments (see the functional perimeter in use case “Get transactions history”)
Note : as this data is issued on the spot via API, the search using “entryReferenceFrom” and/or “entryReferenceTo” parameters is NOT supported
Limits related to eligible payment accounts
Apply to the following customer segments :
- Professionals & corporates (using direct access “BTP Net” online banking and an account starting with 08 with electronic funds transfers and direct debits activated) have the status of “legal entity”. In this case, the payment account is called “current account”
Limits related to SCA means compliant with this API
- Professional PSU equiped with (password + SMS OTP) and/or (CAP reader) and/or (soft token Secur’Pass on smartphone)
- Corporate PSU equiped with (password + SMS OTP) and/or (CAP reader) and/or (physical token TurboSign) and/or (soft token Secur’Pass on smartphone)
Note : if the PSU is only equiped with a physical token, this SCA mean can’t be used on his/her mobile/smartphone
From test to live data
According to PDS2 regulation, the data set available thru this dev portal and sandbox are based on fictive data (or non-real ones).These data are described in the use case “Test our API“.
In order to access to live data, please use first our API Register (see the product data sheet https://developer.bpce.fr/en/caisse-depargne-api-register/).
IMPORTANT NOTE : a weekly slot is reserved for a programmed maintenance (all IT infrastructure incl’d backends and API gateways) Monday morning from midnight to 06:00 am CET, and could generate some perturbations during this period (same for some banking batch processes initiated at the beginning or at the end of the day/month/quarter/year).
For live operations, the parameter “bank code” allows to send API requests to the right ASPSP backend thru a dedicated « endpoint » www.<bank code>.live.api.89c3.com(or www.<bank code>.live.api.btp-banque.fraligned on direct access domain name www.btp-banque.fr).
Once chosen, this entry point shall also be used for all subsequent requests.
bank code | ASPSP name | Bank short name | Available in Sandbox | Available in Production |
30258 | BTP Banque | BTPB | – (*) | Yes |
(*) Note : as this ASPSP is on the same banking system as Caisses d’Epargne (CE), you can use the CE data in sandbox as BTPB will have exactly the same behavior and data format.
Eligibility
The API resources can only be used by Payment Service Providers (PSP) having a Account Information Service Providers (AISP) role.
In order to provide a service to users of account informations services under PSD2 directive, you must be a licenced PSP such as credit institution, electronic money institution, and payment institution. This status is delivered by the financial authorities of the country where the request is made ; in France it is the “Autorité de Contrôle Prudentiel et de Résolution (ACPR), under the supervision of the Banque de France regulatory body :
Obtaining and maintaining such agreement requires rigorous procedures in order to give strong guarantees to the account informations services users. The forms are provided on the ACPR website : https://acpr.banque-france.fr/en/authorisation/banking-industry-procedures/all-forms
Once the agrement is granted, the Organisation Identifier (OID) given by the national authority has the following format (UPPER case):
PSDXX-YYYYYYYY-ZZZZZZZZ
“PSD” as 3 character legal person identity type reference
2 character ISO 3166 country code representing the NCA country
hyphen-minus “-” (0x2D (ASCII), U+002D (UTF-8)); and
2-8 character NCA identifier (A-Z uppercase only, no separator)
hyphen-minus “-” (0x2D (ASCII), U+002D (UTF-8)); andPSP identifier (authorization number as specified by NCA)
This OID is very important to identify yourself as a TPP :
- using STET API requests as OID is included in the parameter “client_ID”
- using mutual authentication (TLS) as OID is included in eIDAS certificates to be delivered to the bank (see below)
Please note that if you are using our API “Register”, an internal OID will be generated & shall be used for subsequent API requests.
You also need eIDAS (electronic IDentification And trust Services) compliant certificates delivered by a Qualified Certification Service Provider (QTSP, see list available on https://webgate.ec.europa.eu/tl-browser/#/).
In order to be able to consume PSD2 API published on our BPCE Developper Portal, the TPP has to enroll its app and to use live certificates signed by a QTSP while sending API Register requests :
- a set of QWAC (for securing the TLS) and QSEALC (to be stored in our gateway) certificates for the sandbox
- another set of (for securing the TLS) and QSEALC (to be stored in our gateway) certificates for the live environment
Note : in case of certificate renewal, and if the QTSP is different (or the same but using different root key elements), the TPP must advise our API support at least 2 months prior the change in order to be able to double check if the new certification authority is loaded on our infrastructure.
A keyID shall also be provided with a correct STET format integrating the SHA256 certificate fingerprint after “_” char, see example STET / Documentation Part 3: Interaction Examples / section 6. AISP Use cases / Signature : keyId=https://path.to/myQsealCertificate_612b4c7d103074b29e4c1ece1ef40bc575c0a87e.
Please embed only public keys. Controls on other data will be based on European Banking Association TPP register (https://euclid.eba.europa.eu/register/pir/disclaimer).
You can also refer to the FAQ section or our virtual assistant for any further question.
Catégories
-
Technical use cases
-
Test our API