How to agregate 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“.
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“.
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 | Fonctionnalités | Sandbox
BPCE API Dev Portal & Sandbox
|
Live
BPCE Live API Gateway |
| v1.0 | Fallback (*) | Non applicable | Fin Septembre 2019 |
Deployment
Deployment(*) 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
1. 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 href=”/www.17515.live.api.caisse-epargne.fr&fallback=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImhF…”>here</a>.</p>
</body></html>
3. Une fois redirigé, le TPP doit utiliser ensuite les identifiants du PSU via sa méthode propriétaire
For more details about POST request, see STET specifications
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)
Sandbox
Introduction
This test environment can be used directly via your app : this mode is described hereafter.
Fictive data are used in this context (see use case “Test with persona“).
Prerequisites
The TPP has to declare its APP using our API REGISTER (see https://www.api.89c3.com/en/component/bpceportal/products/543/usecases/533) in order to forwerd us :
- its organisation agreement identifier (OID) as defined by your national competent authority
- the public keys of the test QWAC & QSEALC eiDAS compliant certificates
- the callback uri (redirect_uri)
Reminder : you have to get your “AISP” agrement.
Step-by-step approach
1st step : request the access token
This token is mandatory to consume API resources.This call triggers the PSU redirection towards his ASPSP. See the use case “Get your token“.Note : if the PSU has accounts in different ASPSP, you need one access token per ASPSP, and therefore, this request has to be used for each ASPSP.
Our entry point depends on ASPSP code : www.<cdetab>.sandbox.api.89C3.com , and for this environment, the only Caisse d’Epargne available is CE Ile de France with <codetab> = 17515.
Example :
GET https://www.17515.sandbox.api.89C3.com/stet/psd2/oauth/authorizeHeaders :Content-Type : application/x-www-form-urlencoded; charset=utf-8Params: response_type:code
client_id:PSDFR-ACPR-13807
redirect_uri:https://www.mycallback.com/
scope:aisp
Remark :
client_id : your organisation agreement identifier as defined by your national competent authority (PSDXX-YYYY-ZZZZZ).
redirect_uri : callback URL as declared in your APP AND to be forwarded to ASPSP for each sandbox and Go Live requests
2nd step : redirection to PSU screens
Once the redirection is activated, the ASPSP displays to PSU identification and authentification screens.
The UX is shown below :
1) PSU can enter his online banking ID thru the identification screen displayed by the ASPSP.
Note : if PSU is a professional or a corporate, another screen requesting the usage number can be displayed.
2) PSU needs to enter his SCA credentials in the authentication screen.
Different SCA means can be used by the PSU (SMS OTP – see below-, soft token, etc.) :
or for the sandbox
In some cases, a notification can be sent to the PSU on his/her mobile phone to activate his PSU means, or to finish this step :
3rd step : get the access token
You can get your access token to be able to consume API resources.
If the PSU has authorized the TPP to access to his payment account (successful SCA), a 1-hour validity unique code will be genereted. It will be used for requesting the access_token useful to consumme API methods (see use case “Get your token“).
Example
POST https://www.17515.sandbox.api.89C3.com/stet/psd2/oauth/token
Header :
Content-Type:application/x-www-form-urlencoded; charset=utf-8
Params :
client_id: PSDFR-ACPR-13807
grant_type: authorization_code
code: NnZx1hqHY2CLkCFjiTwhJeflgFedCBa
redirect_uri:https://www.mycallback.com/
Remarks :
client_id : your agreement number as defined by your national competent authority (PSDXX-YYYY-ZZZZZ).
code : data in callback url
redirect_uri : this data needs to be strictly identical to the “redirect_uri” one used in the GET /authorize request !!!
The QWAC eiDAS certificate has to be sent with this request.
Response :
{
“token_type”: “Bearer”,
“expires_in”: 3600,
“scope”: “aisp”,
“refresh_token”: “KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNewRfrsH”
}
4th step : use the API methods
1) Get the list of accounts
Once the acces token is received, this methods allows the TPP to list tha payment accounts during the first call (see use case “Get accounts list“).
The TPP sequence is as follows :
- GET /accounts to list all available accounts (without any links nor balances neither transactions)
- ask PSU which accounts & data he wants to authorize TPP to get access to
- PUT /consents for sending to ASPSP the list of authorize accounts
- GET /accounts to access to authorized data
Example BEFORE the PUT /consents method:
GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts
Header :
Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf
X-Request-ID: id-1234567890111121 1
Signature: keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<footprint sha256>\“, algorithm=\”rsa-sha256\”, headers=\”(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\”, signature=\”LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QiMViAmthebEst=\”
Psu-IP-Address:192.168.0.1
No body
Remarks :
Psu-Ip-Address => allows to differentiate batch request triggered by the TPP from requests whenever connected PSU to TPP app : so this field has to be filled when the PSU is connected
Response : 200 OK
Headers :
X-Request-ID:id-1234567890111121 1
Body :
{
“_links”: {
“self”: {
“templated”: false,
“href”: “/stet/psd2/v1.4.2/accounts”
}
},
“accounts”: [
{
“cashAccountType”: “CACC”,
“accountId”: {
“iban”: “FR7617515000920400430518020”
},
“usage”: “PRIV”,
“psuStatus”: “Account Holder”,
“name”: “LEA SANDBOXA”,
“currency”: “EUR”
},
{
“cashAccountType”: “CACC”,
“accountId”: {
“iban”: “FR7617515000920400851811524”
},
“usage”: “PRIV”,
“psuStatus”: “Account Holder”,
“name”: “LEA SANDBOXA”,
“currency”: “EUR”
}
]
}
Example AFTER the PUT /consents method:
GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts
Header :
Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf
X-Request-ID: id-1234567890111121 1
Signature: keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<footprint sha256>\“, algorithm=\”rsa-sha256\”, headers=\”(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\”, signature=\”LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxinDocH1ne=\”
Psu-IP-Address:192.168.0.1
No body
Remarks :
Psu-Ip-Address => allows to differentiate batch request triggered by the TPP from requests whenever connected PSU to TPP app : so this field has to be filled when the PSU is connected
Response : 200 OK
Headers :
X-Request-ID:id-1234567890111121 2
Body
{
“_links”: {
“self”: {
“templated”: false,
“href”: “/stet/psd2/v1/accounts”
}
},
“accounts”: [
{
“cashAccountType”: “CACC”,
“accountId”: {
“iban”: “FR7617515000920400430518020”
},
“resourceId”: “175150009204004305180”,
“_links”: {
“balances”: {
“templated”: false,
“href”: “/stet/psd2/v1/accounts/175150009204004305180/balances”
},
“transactions”: {
“templated”: true,
“href”: “/stet/psd2/v1/accounts/175150009204004305180/transactions”
}
},
“usage”: “PRIV”,
“psuStatus”: “Account Holder”,
“name”: “LEA SANDBOXA”,
“currency”: “EUR”
},
{
“cashAccountType”: “CACC”,
“accountId”: {
“iban”: “FR7617515000920400851811524”
},
“resourceId”: “175150009204008518115”,
“_links”: {
“balances”: {
“templated”: false,
“href”: “/stet/psd2/v1/accounts/175150009204008518115/balances”
},
“transactions”: {
“templated”: true,
“href”: “/stet/psd2/v1/accounts/175150009204008518115/transactions”
}
},
“usage”: “PRIV”,
“psuStatus”: “Account Holder”,
“name”: “LEA SANDBOXA”,
“currency”: “EUR”
}
]
}
2) Send PSU consent to ASPSP
See use case “Forward PSU consent“.
Example :
PUT https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.4.2/consents
Headers :
Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf
X-Request-ID: id-1234567890111121 2
Signature: keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<footprint sha256>\“, algorithm=\”rsa-sha256\”, headers=\”(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\”, signature=\”LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QinCept10n=\”
Psu-IP-Address:192.168.0.1
Body
{
“balances”: [
{
“iban”: “FR7617515000920400430518020”
},
{
“iban”: “FR7617515000920400851811524”
}
],
“transactions”: [
{
“iban”: “FR7617515000920400430518020”
},
{
“iban”: “FR7617515000920400851811524”
}
],
“trustedBeneficiaries”: false,
“psuIdentity”: false
}
Response :
201 « Created »
Headers :
X-Request-ID:id-1234567890111121 2
No body
3) Get the balances
See use case “Accounting balances“.
Example :
GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/{accountResourceId}/balances
Headers :
Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf
X-Request-ID: id-1234567890111121 2
Signature: keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<footprint sha256>\“, algorithm=\”rsa-sha256\”, headers=\”(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\”, signature=\”LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1Qincept10n=\”
Response :
200 OK
Headers :
X-Request-ID:id-1234567890111121 2
Body :
{
“balances”: [
{
“balanceType”: “CLBD”,
“name”: “Solde comptable au 28/09/2018”,
“balanceAmount”: {
“amount”: “-150.00”,
“currency”: “EUR”
}
}
],
“_links”: {
“self”: {
“templated”: false,
“href”: “/stet/psd2/v1/accounts/175150009204004305180/balances”
},
“transactions”: {
“templated”: true,
“href”: “/stet/psd2/v1/accounts/175150009204004305180/transactions”
},
“parent-list”: {
“templated”: false,
“href”: “/stet/psd2/v1/accounts”
}
}
}
4) Get transactions history
See use case “Get transactions history“.
Example :
GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.4.2/accounts/{accountResourceId}/transactions
Headers :
Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf
X-Request-ID: id-1234567890111121 1
Signature: keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<footprint sha256>\“,algorithm=\”rsa-sha256\”,headers=\”(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\”,signature=\”LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1T0tOtuTuT1ti=\”
Psu-IP-Address:192.168.0.1
No body
Response :
200 OK
Headers :
X-Request-ID:id-1234567890111121 1
Body
{
“_links”: {
“balances”: {
“templated”: false,
“href”: “/stet/psd2/v1/accounts/175150009204004305180/balances”
},
“self”: {
“templated”: true,
“href”: “/stet/psd2/v1/accounts/175150009204004305180/transactions”
},
“parent-list”: {
“templated”: false,
“href”: “/stet/psd2/v1/accounts”
}
},
“transactions”: [
{
“resourceId”: null,
“remittanceInformation”: [
“Retrait Carte”
],
“entryReference”:”751040043051802019-09-08-05.33.46.621234″,
“transactionAmount”: {
“amount”: “13.00”,
“currency”: “EUR”
},
“bookingDate”: “2019-09-05”,
“creditDebitIndicator”: “DBIT”,
“status”: “BOOK”
}
]
}
5) Get PSU Identity
See use case “Get PSU identity“.
Example :
GET https://www.12579.sandbox.api.89C3.com/stet/psd2/v1.4.2/end-user-identity
6) Get the overdraft
See use case “Get account overdraft“.
Example :
GET https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.6.2/accounts/175159000004003580740/overdrafts
Headers :
Authorization: Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAbCdEf
X-request-id: id-1234567890111121 7
Signature: keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<empreinte sha256>\“,algorithm=\”rsa-sha256\”,headers=\”(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\”,signature=\”LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1T0tOtuTuT1ti=\”
Psu-IP-Address: 192.168.0.1
Pas de body
Réponse : 200 (=> OK)
Headers :
X-request-id: id-1234567890111121 7
Content-Type: application/hal+json;charset=UTF-8
Body :
{
“overdrafts”: {
“allowedAmount”: {
“amount”: 0,
“currency”: “EUR”
}
},
“_links”: {
“self”: {
“href”: “/stet/psd2/v1.6.2/accounts/175159000004003580740/overdrafts”,
“templated”: false
},
“balances”: {
“href”: “/stet/psd2/v1.6.2/accounts/175159000004003580740/balances”,
“templated”: false
},
“transactions”: {
“href”: “/stet/psd2/v1.6.2/accounts/175159000004003580740/transactions”,
“templated”: true
},
“parent-list”: {
“href”: “/stet/psd2/v1.6.2/accounts”,
“templated”: false
}
}
}
7) Refresh your access token
See use case “Refresh your token“.
Example :
POST https://www.12579.sandbox.api.89C3.com/stet/psd2/oauth/token
Header :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
Params:
client_id: PSDFR-ACPR-13807
grant_type: refresh_token
refresh_token: KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAbCdEf
Response :
{
“token_type”: “Bearer”,
“expires_in”: 3600,
“scope”: “aisp offline_access”,
“refresh_token”: “KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAbCdEf”
}
Test with persona
Introduction
As required by PSD2 regulation (see RTS Art. -30 (5)), we deliver a testing facility, including support, for connection and functional testing using non-real test data. These personna are gathered using banking segments (retail, corporate) and customer segmentation (student, young active, professionnal, retired, etc…).
Expected API input data are listed (PSU id, IBAN). PSU consent has already been recorded. These data included the accounting balance are static (no changes).
Please note that this test dataset will evolve overtime with additional profiles and data history (volume, depth). So stay informed and visit this dev portal regularly!
PSU ID & TEST DATA AS DESCRIBED BELOW CANNOT BE USED IN PRODUCTION LIVE ENVIRONMENT.
Personas
 |
 |
|
LEA SANDBOXA
|
CLAIRE RECETTEB
|
 |
 |
GEORGES PERSONAC
|
GILLES TESTUNID
|
Please note that in the assembly mode, you’ll have to enter OTP SMS = « 12345678 » for all persona whenever the authentication screen is proposed.
WARNING : NEW ID NUMBER
| Persona | Segment | New
Id |
Bank code | IBAN | Payment account holder | PSU consent : balance/ Transactions / Identity |
Balance | Currency |
| LEA SANDBOXA | Particulier | 9999999901 | 17515 | FR7617515000920400430518020 | LEA SANDBOXA | TRUE TRUE FALSE |
-150.00 | EUR |
| CLAIRE RECETTEB | Particulier | 9999999902 | 17515 | FR7617515900000400358074026 | CLAIRE RECETTEB | TRUE TRUE FALSE |
0.00 | EUR |
| CLAIRE RECETTEB | Entrepreneur individuel | 9999999902 | 17515 | FR7617515900000800358074006 | CLAIRE RECETTEB | TRUE TRUE FALSE |
+23766.98 | EUR |
| GEORGES PERSONAC | Particulier | 9999999903 | 17515 | FR7617515000920400085945890 | Mr et Mme GEORGES PERSONAC | TRUE TRUE FALSE |
+10.00 | EUR |
| GILLES TESTUNID | Particulier | 9999999904 | 17515 | FR7617515000920440878790811 | Mr GILLES TESTUNID | TRUE TRUE FALSE |
+11880.30 | EUR |
| GILLES TESTUNID | Particulier | 9999999904 | 17515 | FR7617515000920402428687756 | Mr OU Mme GILLES TESTUNID | TRUE TRUE FALSE |
0.00 | EUR |
| GILLES TESTUNID | Particulier | 9999999905 | 17515 | FR7617515000920402428748381 | Mr ET Mme GILLES TESTUNID | TRUE TRUE FALSE |
+5879.22 | EUR |
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 on August 31, 2017), 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://www.api.89c3.com/en/contact-us). 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 :
| MÉTHODE(S) | DATE | DESCRIPTION DE L’ÉVOLUTION |
| All | October 20, 2022 | Alignment on PSD2 API STET v1.6.2.0 |
Roadmap
Politique de décommissionnement des versions de l’API
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
L’API d’Information sur compte fait l’objet d’améliorations et d’évolutions continues tout au long de l’année*.
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 | Features | Deployment date
Dev Portal & Sandbox |
Deployment date
BPCE Live API Gateway |
Deprecation date
BPCE Live API Gateway |
| v1.6.2 | 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 Caisse d’Epargne online banking service interfaces)
- Access to customer account holder identity (first name and last name) 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 (/!\ /transactions method with or without dateFrom / dateTo parameters is considered as one method)
- The optional STET data “entryReference” applies only to PART & PRO/EI customer segments (see the functional perimeter in use case “Get transactions history”)
- The optional STET data “dateType” is not supported
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 :
- Retail customer who subscrided direct access “DEI PART” online banking. In this case, the payment account starting with 04 is called a “deposit account”, and includes joint account, as well as attached minor to the account family.
Note 1 : the legal guardian or representative using Web Protexion solution (for managing persons under tutorship / curatorship) is not supported
Note 2 : a retail customer is a “physical individual” having the legal status of “capable adult”. He/she may have small professionals activities using the legal status “individual entrepreneur”, and is considered as a retail customer
- Large professional & corporate using direct access “CE Net” online banking (having a subcription “CE Net Compte” and an account starting with 08 with electronic funds tranfers and electronic 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
- Retail PSU equiped with (password + SMS OTP) and/or (CAP reader) and/or (Sécur’Pass on smartphone)
- Professional PSU equiped with (password + SMS OTP) and/or (CAP reader) and/or (Sécur’Pass on smartphone)
- Corporate & association PSU equiped with (password + SMS OTP) and/or (CAP reader) and/or (physical token TurboSign) and/or (Sécur’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, Try-it mode 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 www.api.89c3.com/en/component/bpceportal/products/543/usecases/533).
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.caisse-epargne.fr aligned on direct access domain name www.caisse-epargne.fr).
Once chosen, this entry point shall also be used for all subsequent requests :
| Bank code | Bank name | Bank short name | Available in Try-it and Sandbox | Available in production |
| 11315 | Caisse d’Epargne Provence Alpes Corse | CEPAC | – | Oui |
| 11425 | Caisse d’Epargne Normandie | CEN | – | Oui |
| 12135 | Caisse d’Epargne Bourgogne Franche-Comté | CEBFC | – | Oui |
| 14445 | Caisse d’Epargne Bretagne-Pays de Loire | CEBPL | – | Oui |
| 13135 | Caisse d’Epargne Midi-Pyrénées | CEMP | – | Oui |
| 13335 | Caisse d’Epargne Aquitaine Poitou-Charentes | CEAPC | – | Oui |
| 13485 | Caisse d’Epargne Languedoc-Roussillon | CELR | – | Oui |
| 13825 | Caisse d’Epargne Rhône Alpes | CERA | – | Oui |
| 14265 | Caisse d’Epargne Loire Drôme Ardèche | CELDA | – | Oui |
| 14505 | Caisse d’Epargne Loire-Centre | CELC | – | Oui |
| 17515 | Caisse d’Epargne Ile De France | CEIDF | Oui | Oui |
| 18315 | Caisse d’Epargne Côte d’Azur | CECAZ | – | Oui |
| 18715 | Caisse d’Epargne Auvergne et Limousin | CEPAL | – | Oui |
| 15135 | Caisse d’Epargne Grand Est Europe | CEGEE | – | Oui |
| 16275 | Caisse d’Epargne Hauts de France | CEHDF | – | Oui |
