-
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 /accounts/balances and GET /accounts/transactions methods.
Access to this method is limited to a maximum of 4 batch per day for one given TPP and 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 V1.4.2.17 / Part II / section 4.2 page 27
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 from our customer (without balances, URI or ressourceID) for the following methods GET /accounts/balances, GET /accounts/transactions and GET /end-user-identity.
IF YOU HAVE ALREADY FORWARDED AT LEAST ONE CONSENT FROM THE CUSTOMER
(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 /accounts/balances method if this account is flagged in the “balances” parameter in PUT /consent
- URI for the GET /accounts/transactions method if this account is flagged in the “transactions” parameter in PUT /consent
- Get payment account holder identity if the field “psuIdentity” has been setup at TRUE value in the 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 mandatoryas 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, the GET / accounts method will not return the information requested but only the list of all current accounts (principle of “AISP mixed consent”).
Request
Method “PUT /consents”
See also STET specification V1.4.2.17 / Part II / section 4.4. / page 15.
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
- psuIdentity : access to PSU identity (name & surname for retail customer, ot corporate ID for a company)
- trustedBeneficiaries : access to the trusted beneficiaries list that have been set by the PSU => this feature is not supported by the ASPSP online banking. So whatever value is used (True/False), it won’t be used.
The AISP forwards details of PSU consent to the ASPSP through this call. The consent is recorded by the ASPSP for one given PSU, one given AISP, one given operation and one given account (except for the psuIdentity and the trustedBeneficiairies access types).
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 account is transmitted with the PUT /consents method and that consent was given for some accounts with a previous call to this method, then it means that the customer is revoking all his accounts.
- If no account is consented, or if the customer has revoked all this consented accounts, the GET /accounts method allows to get all the accounts list but access to related data (balances, transactions) is NOT possible anymore.
- 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 V1.4.0.47 / Part III / section 5.3 / page 7
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 authorized 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 and 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 /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
Method “GET /accounts/{accountResourceId}/balances”
See also STET V1.4.2.17 / Part III / section 6.4/ page 9
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 V1.4.2.17 / Part II / section 4.3.4 / page 31
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 on a payment account authorized by the customer.
The type of account is 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
Method “GET /accounts/{accountResourceId}/transactions”
See also STET V1.4.2.17 / Part II / section 4.4 / page 34
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.
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
The date format for dateFrom et 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 V1.4.2.17 / Part III / section 6.5 / page 10
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 specificationSTET V1.4.2.17 / Part II / section 4.6.4 / page 43
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.
Your access to this method are limited to a maximum of 4 batch accesses per calendar day, for a customer. However, when it is the connected customer who directly interrogates his current accounts, the number of accesses is not limited.
Example
You can find an example of this request in section “Test our API” and then “Use our sandbox“.
See also specificationSTET V1.4.2.17 / Part III / Section 6.3 / page 8
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 |
Try-it mode
Principle
If you are connected on the BPCE API dev portal, you can :
- call any API through the menu in which you select your app and the access token
- then you enter the requested parameters of the method that you want to test (headers or body), those mandatory are flagged (with a “*”)
Once done, you can execute the request and get the result (incl’d error message) based on non-real persona test data as requested by the regulation (see the use case “Test with persona“).
Please note that you need to execute the request “GET /accounts” before the methods “GET /accounts/transactions” and “GET /accounts/balances” in order to retrieve the “ressourceId” parameter requierd.
Version 1.4.2
As of July 8, 2020, Try-it will only be possible for version V1.4.2.
If you have already applied for GoLive or used the self-enrolment API REGISTER , then you must create a new application and select the new STET API V1.4.2.
If you have NOT made a GoLive request, you can :
- either modify your existing application to associate it with the new STET V1.4.2 API
- either create a new application, then select the new STET V1.4.2 API
Try-it parameters for the API “Account information”
NB : for the parameter “body”, you can copy and paste the examples (left part of the screen) in the form on right part of the screen and apply your changes.
Common parameters to all methods
| Parameter |
Description |
Data type |
Parameter type |
Mandatory |
| Authorization |
access token in header |
Char |
Header |
Yes |
| PSU-IP-Address |
IP address used by the customer logged-in to you app
*mandated if the PSU is connected, otherwise “blank” if you use the batch mode |
Char |
Header |
No* |
| PSU-IP-Port |
IP port of the device used by the PSU connected to your app |
Char |
Header |
No |
| PSU-HTTP-Method |
http method used for the request |
Char |
Header |
No |
| PSU-Date |
Timestamp used for the PSU request |
Char |
Header |
No |
| PSU-GEO-Location |
Geographic location given by the PSU if available |
Char |
Header |
No |
| PSU-User-Agent |
Header “User-Agent” sent by the PSU device connected to your app |
Char |
Header |
No |
| PSU-Referer |
Header “Referer” or “Referrer” sent by the PSU device connected to your app |
Char |
Header |
No |
| PSU-Accept |
Header “Accept” sent by the PSU device connected to your app |
Char |
Header |
No |
| PSU-Accept-Charset |
Header “Accept-Charset” sent by the PSU device connected to your app |
Char |
Header |
No |
| PSU-Accept-Encoding |
Header “Accept-Encoding” sent by the PSU device connected to your app |
Char |
Header |
No |
| PSU-Accept-Language |
Header “Accept-Language” sent by the PSU device connected to your app |
Char |
Header |
No |
| Digest |
Body synthesis |
Char |
Header |
No |
| Signature |
HTTP request signature (see https://datatracker.ietf.org/doc/draft-cavage-http-signatures/)
The header field “keyId” should be formatted as KeiId=”SN=XXX,CA=YYYYYYYYYYYYYYYY” in which “XXX” is the serial number (hex format) of the QSEAL certificate QSEAL
“YYYYYYYYYYYYYYYY” is the full name of the certification authority having issued this certificate
A message HTTP 400 will be returned by the server in case of an invalid or missing signature |
Char |
Header |
Yes |
| X-Request-ID |
Consistency Header parameter to be included in the request, and it has to be returned in the response |
Char |
Header |
Yes |
Parameters dedicated to GET /accounts/{}/balances
| Parameter |
Description |
Data type |
Parameter type |
Mandatory |
| accountResourceId |
Main identification of the account resource to fetch and used as input paramater by the request. It is obtained as the “GET /accounts” result in the “ressourceId” field |
Char |
Path |
Yes |
Parameters dedicated to GET /accounts/{}/transactions
| Parameter |
Description |
Data type |
Parameter type |
Mandatory |
| accountResourceId |
Main identification of the account resource to fetch and used as input paramater by the request. It is obtained as the “GET /accounts” result in the “ressourceId” field |
Char |
Path |
Yes |
| dateTo |
Exclusive maximal imputation date of the transactions (transactions having an imputation date equal to this parameter are NOT included in the result) |
Char |
Request |
No |
| dateFrom |
Inclusive minimal imputation of the transactions (= those having an imputation date equal to this parameter are included in the result) |
Char |
Request |
No |
| afterEntryReference |
Specify the value on which the result has to be computed. Only transactions having a technical id GREATER than this value must be included in the result |
Char |
Request |
No |
Sandbox
Introduction
This test environment can be used in 2 ways :
- Try-it mode on BPCE API portal (see use case “Try-it mode“) ;
- either directly via your app : this mode is described hereafter.
Fictive data are used in this context (see use case “Test our persona“).
As this ASPSP is based on the same backed as Caisses d’Epargne (CE) one, you can use in sandbox the CE test cases as described in “https://www.api.89c3.com/en/component/bpceportal/products/452/usecases/447“.
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 :
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.
You can consult the virtual assistant on this portal.
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 version of this documentation was published :
| Method(s) |
Effective date |
Description of the evolution |
| All |
October 30, 2020 |
See all previous evolutions on Version V1 API |
| All
GET /accounts/../transactions |
December 21, 2020 |
Add a new entry point / “limitations” section
Status change from “PDNG” to “OTHR” |
| All |
January 28, 2021 |
Add new customer segments / “limitations” section |
| GET /accounts/../transactions |
Februray 03, 2021 |
Add optional STET data “entryReference” / “limitations” section & “get transactions history” use case |
| GET /accounts/../transactions
Fallback
Refresh the access Token |
September 29, 2021 |
Add optional STET data “bankTransactionCode” (for PRO & CORP)
Add impacts of the new online banking solution
Add a note on revocation process |
| Roadmap |
October 30th, 2021 |
Note on urgent changes out of regulatory notice period |
| All |
January 3rd, 2022 |
Editorial issues and SCA updates |
| Overview |
August 28, 2022 |
Editorial issues and App2App updates |
Roadmap
Deprecation process
According to API product life cycle, an API version can be deprecated (means 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 on the deprecation 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
- evolutions requested by the national competent authority
Please do find below our forecast roadmap :
| Our API versions |
STET Standard versions |
Features |
Sandbox
Deployment date
BPCE API Dev Portal & Sandbox |
Live
Deployment date
BPCE Live API Gateway |
Live
Deprecation date
89C3 Live API Gateway |
| v1.4.2 |
v1.4.2.17 |
API version v1
- Get the list of current accounts of a customer
- Get a customer’s account balances report
- Get a customer’s account transactions history
- Forward to ASPSP the list of accounts granted for accessing to balances and/or transactions and/or account holder identity
Plus
- Alignment with STET V1.4.2 specification including “Obtain PSU’s identity”
- Customer experience improved
|
July 17, 2020 |
October 22, 2020 |
To be announced |
| v1.6.2 |
v1.6.2.0 |
To be announced |
End of 3Q2022 (est.) |
End of 1Q2023 (est.) |
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 /consent 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 BTP Banque online banking service)
- 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 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 PRO 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
- Corporate PSU equiped with password + SMS OTP and/or CAP reader and/or physical token TurboSign
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).
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, 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 “bankcode” allows TPP to send API requests to the right ASPSP backend thru a dedicated « endpoint » www.<bkcode>.live.api.89c3.com(or www.<bkcode>.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 |
Bank name |
Bank short name |
| 30258 |
BTP Banque |
BTPB |
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 :
https://acpr.banque-france.fr/sites/default/files/medias/documents/jch_20180403_conference_securite_des_paiements.pdf
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
A keyID shall also be provided with a correct STET format integrating the SHA256 certificate fingerprint after “_” char, see example STET V1.4.2 / 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.
