Regulatory publications

Retrieve your token

Access to the "account information" or "fund availability" APIs is granted via an access token (access_token) that can be obtained by following the OAuth2 standard.

Token Retrieval Sequence

1. Our client (PSU) indicates to you the identity of their account-holding institution.

2. You initiate the OAuth2 access token retrieval sequence by redirecting the client (PSU), via their web browser, to the authorization infrastructure of the account-holding institution (ASPSP) using the command: GET /authorize

   See also the STET specification V1.4.0.47 / Part I / section 3.4.3.2 / page 21.

3. The account holder (ASPSP) will:
   • Identify and authenticate its client using one of the strong authentication methods it offers and presents to the client;
   • Perform checks related to your profile as an AISP or CBPII (validity of your QWAC and QSEALC certificates and your role, non-revocation of your profile, etc.)

4. Once these checks are completed and if they are conclusive, the bank will redirect the client (PSU) to your site using your "callback" (redirection) URL that you provided to us during the "Go Live" process.

   Indeed, the AISP must specify for its consumer APP a URL that will be called by the bank:

   • If the PSU has authorized the retrieval of their data by the AISP
   • Or in the event of consent refusal
   • Or if the identification and authentication sequence is interrupted at any of its steps (e.g., timeout on the identification screen or on the strong authentication screen).

   If the PSU has allowed you to retrieve their data from their account holder, you will find in the response to this call a one-time use code that has a short lifespan.

5. Via a POST /token call, you can then directly request the account holder for your OAuth2 access token (access_token) with the elements received previously, including the one-time use code.

   Note: /token requests from the Authorization Code flow must be sent WITHOUT the "scope" parameter.

   See also the STET specification V1.4.0.47 / Part I / section 3.4.3.2 / page 22.

6. The account holder (ASPSP) will:
   • Perform checks related to your profile as an AISP or CBPII (validity of certificates and your approval, non-revocation of your profile, etc.)
   • Identify and authenticate you as an AISP or CBPII via your certificate that you will provide to secure the mutual exchange.

7. Once these checks are completed and if they are conclusive, the account holder will send you an HTTP 200 (OK) response containing, among other things, the OAuth2 access token (access_token).

   See also the STET specification V1.4.0.47 / Part I / section 3.4.3.2 / page 23.

8. Once the OAuth2 access token (access_token) issued by the bank has been retrieved by you, you can present it to consume the resources of the API.

   This token is accompanied by a refresh_token valid for 180 days that you must keep. When your access_token expires, you can request a new one by following the section "Overview" > "Refresh your token".

   After 180 days, your refresh_token will expire. To obtain a new one, you will need to go through this "Retrieve your token" sequence again and, in fact, undergo a new strong authentication step for the client with their bank (see point 3 above).

For more details, also see the OAuth 2.0 Authorization Framework: https://tools.ietf.org/html/rfc6749#section-4.1

Example

An example request is provided in the section "How to Test the API ?" > "Sandbox Assembly".

Use and check funds availability

Use case

This call allows to check if a given amount can be covered by the liquidity that is available on a PSU (Payment Service User) cash account or payment card.

Prerequisite

In order to process this request some eligibility prerequisites are needed, like to get the OAuth2 access token (see the use case “Retrieve your token”) and to provide the body parameters.

Request

POST /funds-confirmations

Mandatory body parameters needed for this service call

• paymentCoverageRequestId: Payment request identifier
• instructedAmount: The structure including the specified amount as well as the currency
  • currency: Currency of the specified amount
  • amount: Amount that will determine if the funds are available
• accountId: Unique identifier for the specified account
• iban: International Bank Account Number (IBAN)

Result returned

The returned result will include the information from the request as well as the response regarding the availability of funds in the form of a boolean.

A self link will also be present to return to the page obtained immediately after the execution of the request.

Example

Request

POST http://localhost:8080/v1/funds-confirmations

Body

{ 

« paymentCoverageRequestId » : « MyCoverage123456 »,

« instructedAmount » : {

« currency » : « EUR »,

« amount » : « 12345 » },

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

}

Result

Status code: 200

Body
{

« request » : {

« paymentCoverageRequestId » : « MyCoverage123456 »,

« instructedAmount » : {

« currency » : « EUR »,

« amount » : « 12345 » },

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

},

« result » : true,

« _links » : {

« self » : {

« href » : « v1/funds-confirmations »

}

}

}

Refresh your token

Principle

Since OAuth2 tokens have a limited lifespan, you need to request a refresh before they expire.

Basic Rules

The account servicing payment service provider (ASPSP) can have at most one valid access token (access_token) and one refresh token (refresh_token) per client PSU / TPP / AISP or CBPII role triplet.

• The access token has a short validity period (approximately one hour max) on a device or application of our client.
• The refresh token has a lifespan of 180 days.
• The refresh token and the access token must be revocable at any time.
• If the access token is revoked, then the refresh token must also be revoked, and vice versa.

Mechanism for refreshing your access token (access_token)

1. You request the renewal of the access token from the ASPSP.
2. The ASPSP initiates the renewal of the access token.
3. The ASPSP retrieves the TPP's certificate from the registry.
4. The ASPSP checks the validity and non-revocation of the presented certificate.
5. The ASPSP checks the date of the last authentication (< 180 days).
6. The ASPSP sends you the new access token and the old refresh token.
7. You securely store the authorization token and the old refresh token.
8. The ASPSP invalidates the old authorization token.

Example

An example of a request is provided in the section "How to test the API ?" > "Sandbox assembly".

API version decommissioning policy

The decommissioning policy (i.e., the cessation of an API version on production and sandbox environments) is based on the API lifecycle, and a transition phase between two major API versions is planned, as indicated in the diagram below:

Image

The communication regarding the decommissioning of version N will occur on the deployment date of version N+1. The preferred communication channel is the BPCE API portal in the "Roadmap" section of the impacted API. Communication via email to the contacts of the providers registered on the BPCE API portal may supplement this arrangement.

Planning for upcoming functional changes to the API

This API is subject to continuous improvements and developments. Article 30 (4) of the RTS specifies that significant changes to the API can occur without delay. We apply this clause in the following cases:

• Blocking issues that broadly impact at least one major customer segment (individuals, professionals, businesses)
• Security issues
• Changes requested by the competent national authorities to comply with regulatory requirements

Functional limitations

The limitations of this PSD2 API are as follows:

• Applies only to euro payment accounts that are eligible (not blocked or under custody) and accessible online (see the text of the PSD2 Directive).
• Covers only the segments of individuals (deposit accounts) and professionals/sole proprietors (current accounts).
• Uses only the redirection authentication method (Strong Customer Authentication requested and managed via the bank).
• Allows access only via the IBAN of the payment account (and not via the identifier of your payment instrument).

Note: The TPP does not have the ability to provide the ASPSP with the customer's personalized security data for authentication purposes; therefore, only the ASPSP's redirection and strong authentication (SCA) screens should be used (the encapsulation of these screens by the TPP is prohibited under PSD2 Article #97.5 and RTS #31).

Access to Production Data

To access real data, please first use our "PSD2 Registration" API.

As with other PSD2 APIs, the establishment code will allow you to address the correct customer reference through an access point in the format:

www.<cdetab>.oba-bad-me-live.api.89c3.com (new URL to be considered from now on)
(As a reminder, the existing URL www.<cdetab>.live.api.89C3.com will no longer be available from September 28, 2025).
 

Examples:

• STET V1.4.0 POST https://www.30007.oba-bad-me-live.api.89c3.com/stet/psd2/v1/funds-confirmations ( /!\ scope = piisp )
• STET V1.4.2 POST https://www.30007.oba-bad-me-live.api.89c3.com/stet/psd2/v1.4.2/funds-confirmations ( /!\ scope = cbpii )
• STET V1.6.2 POST https://www.30007.oba-bad-me-live.api.89c3.com/stet/psd2/v1.6.2/funds-confirmations ( /!\ scope = cbpii )

Eligibility

The resources of this API can only be consumed by PSPs with the role "CBPII" or "PIISP" depending on the STET version used. This status is granted by the financial authorities of the country where the application is made; in France, it is the Autorité de Contrôle Prudentiel et de Résolution (ACPR), linked to the Banque de France.

Obtaining and maintaining a license involves rigorous procedures to provide strong guarantees to users of payment services, with forms available on the ACPR website: https://acpr.banque-france.fr/autoriser/procedures-secteur-banque/tous-les-formulaires.

Once the license is granted, the format of this identifier (Organization Identifier = OID) provided by the competent authority is PSDXX-YYYYYYYY-ZZZZZZZZ:

• XX => ISO 3166 code of the country of the competent authority
• hyphen-minus "–" (0x2D (ASCII), U+002D (UTF-8))
• YYYYYYYY => 2-8 characters of the identifier of the competent authority (A-Z, no separator)
• hyphen-minus "–" (0x2D (ASCII), U+002D (UTF-8))
• ZZZZZZZZ => identifier of the PSP specified by the competent national authority (no restrictions on the number – or type – of characters used)

This OID identifier is important for two reasons:

• It will be used to identify you during API STET requests (via the "client_id" parameter).
• It must be present in the eIDAS certificates you provide to the account servicing provider (see below).

Additionally, you must have certificates issued by a recognized certification authority (Qualified Certification Service Providers – QTSP: https://webgate.ec.europa.eu/tl-browser/#/) in compliance with the eIDAS regulation (electronic IDentification And trust Services: https://www.ssi.gouv.fr/entreprise/reglementation/confiance-numerique/le-reglement-eidas/) and adhering to the ETSI standard (https://www.etsi.org/deliver/etsi_ts/119400_119499/119495/01.02.01_60/ts_119495v010201p.pdf).

To consume the DSP2 APIs offered on the BPCE group portal, you will need to provide us with your QWAC and QSEALC certificates:

• For production for the operation of the assembly in the sandbox (if available for this ASPSP).
• For production during calls on our BPCE API Live gateway.

Note: In the event of certificate renewal, and if the certification authority (QTSP) is different (or it is the same QTSP company but using different root keys), the TPP must notify API support available through this site two months in advance to ensure that the elements of the new AC are properly loaded onto our infrastructure.

A keyID identifier must also be provided in a format compliant with the STET specification, incorporating a SHA256 fingerprint after the character "_" char, see example STET V1.4.2 / Documentation Part 3: Interaction Examples / section 6. AISP Use cases / Signature: keyId=https://path.to/myQsealCertificate_612b4c7d103074b29e4c1ece1ef40bc575c0a87e.

Only public keys in .pem format are required. Controls on the certificate data will be performed based on French (REGAFI: https://www.regafi.fr) and European (ABE or EBA: https://euclid.eba.europa.eu/register/pir/disclaimer) registers.

Planning for upcoming API developments

In accordance with Article 30 (5) of the RTS, assistance for third-party PSP providers is available. This support can be accessed via the form on this BPCE API portal. Responses are provided during business hours.

The general principle of support is illustrated below, taking into account the regulatory timelines specified in Article 30 (4) of the RTS:

Image

Versionning

Significant changes made since the last delivered version