Regulatory publications

CBPII Process

This process describes the CBPII case implementation with the description of every step, since the token retrieval until the Funds availability request.
 

Step 1 – Prerequisite

You must enroll on BPCE API and when you subscribe to live with CBPII role, you have to provide QWAC and QSEAL certificates. Your CBPII role will be checked on the basis of information get in the REGAFI.

 

Step 2 – Access authorization as a CBPII which is provided by our connected customer

For every of our customers, you should get an initial access token worth for 180 days:

a) After asking our connected customer on your application in which Banque Populaire his accounts are based, you must submit an access token retrieval request for this customer (see the use case “Retrieve your access token”)

b) Our customer is redirected to a mobile interface of this Banque Populaire in order to identify himself

c) Our customer processes a strong authentication in this mobile interface which generates an access token

d) You get the initial access token for this customer

 

Step 3 – Funds availability request

When our customer needs to process to a purchase with his private card, you check the customer account solvency with the POST /funds-confirmations method by providing your access token for this customer (see the use case “Check funds availability”)

 

Step 4 – If the 180 days token has expired, you must ask a token refresh for the customer

a) With our connected customer on your application, you submit a refresh request for this customer token (see the use case “Refresh your access token”)

b) Our customer is redirected to a mobile interface of his Banque Populaire and processes a strong authentication in this mobile interface, which reactivates the access token

c) You get the refresh token for this customer

Get your access token

Principle

Access to PSD2 API is granted by the bank with an authorization token (or access token) issued using OAuth2 standardized process.

 

Retrieval of access token sequence

1. Our customer (PSU) provides you the identity of the Banque Populaire which holds his accounts.

2. You initiate the OAuth2 access token recovery sequence by redirecting the customer through his web browser to Banque Populaire authorization infrastructure using GET /authorize.

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

3. The Banque Populaire account manager (ASPSP) will:

• Identifies and authenticates the PSU using one of the strong authentication methods proposed and presented to the customer
• Check your role and validity of your eIDAS certificates and agreement.

4. Once checks are done and correct, ASPSP will redirect the PSU to your site using “call-back” URL given in the GET /authorize and to ASPSP for the Go Live process.

Indeed, the AISP must specify for its consuming APP, a URL which will be called by the banking establishment:

• if the customer has authorized the recovery of its data by the AISP;
• or in case of refusal of consent;
• or if the kinematics of identification and authentication are interrupted at one of its stages (example: timeout on the identification screen or on the strong authentication screen).

You will find in the response of this request a one-time-token with a short life period.

5. You can then call the Banque Populaire in order to request the OAuth2 token access_token (and refresh one refresh_token) using POST /token with previously received data (include the one-time-token).

Note: these /token requests for getting the Authorization Code flow shall be sent WITHOUT the « scope » parameter.

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

6. The Banque Populaire account manager (ASPSP) will:

• Check your role (AISP or CBPII) and validity of your eIDAS certificates and agreement
• Check 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, the Banque Populaire returns a response HTTP 200 (OK) with data including the access_token.

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

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 using the use case “Refresh your access token”. If your refresh token is about to expire, you will have to perform again all this process “Get your access token” (see point 3 above), meaning also redirect to Banque Populaire for customer’s strong authentication (customer 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 “Use our sandbox“.

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 access token”) and to provide the body parameters.

Request

POST /funds-confirmations

Body parameters 

• paymentCoverageRequestId – mandatory: Payment request ID
• payee – facultative: The merchant where the card is accepted as information to the PSU
• instructedAmount – mandatory: The structure embedding the amount and the currency to be used
  • currency – mandatory: The currency of the amount
  • amount – mandatory: Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party
• accountId – mandatory: Unique and unambiguous identification for the account between the account owner and the account servicer.
  • iban – facultative: International Bank Account Number (IBAN)
  • other – facultative: Unique identification of an account, a person or an organisation, as assigned by an issuer
    • identification – mandatory: API Identifier
    • schemeName – mandatory: Name of the identification scheme (BANK, COID, SREN, SRET, NIDN, OAUT, CPAN)
    • issuer – facultative: Entity that assigns the identification
  • currency - facultative :  the currency of the amount or of the account.

Result returned

The structure of the returned result embeds the original request and the result of the availability as a Boolean.

A self link will also be displayed in order to go back to the page obtained right after the request execution.

Example

Request

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

Body
{
“paymentCoverageRequestId”: “MyCoverage123456”,
“instructedAmount”: {
“currency”: “EUR”,
“amount”: “123.45”,
“accountId”: { “iban”: “FR7613807008043001965405158” }
}

 

Result

Status code: 200

Body
{ “result”: true, “request”: { “accountId”: { “iban”: “FR7613807008043001965405158” }, “paymentCoverageRequestId”: “MyCoverage123456”, “instructedAmount”: { “amount”: “123.45”, “currency”: “EUR” } }, “_links”: { “self”: { “href”: “https://www.rs-sandbox.api.89c3.com/stet/psd2/v1/funds-confirmations” } }}

(data set Marc’s persona -D0999990I0)

Acceptation 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.

Refresh your access token

Principle

Since the access token has a short validity, it is necessary for the TPP to request its refresh before it expires.

Basic rules

The Banque Populaire account manager (ASPSP) has at most one valid access token and one valid refresh token per customer (PSU)/TPP/Role AISP or CBPII triplet.

• The access token has a short validity period (of about one hour) on an isolated device or a client application of our customer.
• The refresh token is valid up to 180 days;
• The refresh token and the access token must be able to be revoked at any time;
• If the Authorization token is revoked, then the refresh one is automatically revoked (and the other way round).
   

This is the sequence of the access token refreshing

1. You ask for the refreshing of the access token to the Banque Populaire.

2. The Banque Populaire initiates the refreshing of the access token.

3. It retrieves the TPP certificate from the registration authority.

4. It checks the validity and non-revocation of the certificate presented.

5. It checks the date of the last authentication (< 180 days).

6. It sends you the new access token and the old refresh token.

7. You store the access token and the old refresh token in a safe place.

8. The Banque Populaire revokes the old access token.

Roadmap

The “Funds Availability” API is subject to continual reviews and improvements throughout the year. Find below our provisional roadmap:

Functional Limitations

These are the operational limitations of this PSD2 API:

• Can be used for all Banque Populaire banking institutions except BRED.
• Only apply to active payment accounts that are accessible online (cf. PSD2 Directive texts) => the balance request will be possible only for a payment account.
• Use the authentication with redirect only (Strong Customer Authentication required and handled by the bank).
• There will be no blockage or reservation of funds.
• The access to informations will be made only through an IBAN => the Banques Populaires don’t own your private cards references.

Limitations on data

The list of current available bank institutions for this API is detailed below. The bank code <cdetab> is used to address to the proper customer reference base via the endpoint  in the format www.<cdetab>.oba-bad-me-live.api.89c3.com (new URL to be considered as of now). 

(As a reminder, the existing URL www.<cdetab>.live.api.89C3.com will no longer be available starting from 28 September 2025).

Examples for this ASPSP:

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

Eligibility

The “Funds availability” API resources can only be used by Payment Service Providers (PSP) with a “Card Based Payment Instrument Issuer” role (CBPII or PIISP depending on the STET version).

In order to provide a service to users of payment services under PSD2 directive, you must be a licensed PSP such as credit institution, electronic money institution, and payment institution. This status is delivered by 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 an authorization requires rigorous procedures in order to give strong guarantees to the payment services users.

The forms are provided on the ACPR website: https://acpr.banque-france.fr/autoriser/procedures-secteur-banque/tous-les-formulaires

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 Portal, you have to forward us using .pem format:

• QWAC and QSEALC live certificates for the sandbox (if available for this ASPSP)
• QWAC and QSEALC live certificates for our BPCE API Live gateway

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 about the principle of eligibility.

Important changes

Important changes made since the first version delivered