Banque populaire – Funds Availability

How to reduce non-payment risks ?

A customer, holding a payment card delivered by your institution, carries out an e-commerce transaction with this card. The customer previously granted authorization to your institution.

Through the “Funds Availability” API, provided by the bank, your institution can ask to check if a given amount can be covered by the liquidity that is available on the customer cash account or payment card, minimising the risk of non-payment.

The bank answers with positive or negative response, without setting aside the amount or executing the transaction..

The “Funds Availability” API resources (see the use case “Use and check funds availability”) can only be consumed by the PSP having the Card Based Payment Instrument Issuer role, this prerequisite is described in the “Eligibility” section.

One this prerequisite completed, the global process is:

1- The customer and you have a contract and he owns a card that you issued. This card allow debits on one of the customer’s accounts held by his bank. The customer has acces to your application.

2- First of all, before any payment coverage check request, the customer must have forwarded his consent to his bank, giving you access to his account for 180 days.

3- If authorization was granted by the customer, you can ask for an OAUTH2 access token retrieval, using BPCE platform and according to secured exchanges (see the use case “Retrieve your access token”)

4- After providing this access token, which is needed to use our API, you will be able tu reduce you non-payment risks by asking the bank to check if a given payment can be covered or not by the funds available on one given customer account for a 180 days period, before asking the customer to process again the strong authentication every 180 days in order to renew your access to his accounts.

The full process description explaining how to consume Funds Availability API is visible in the use case “CBPII Process”.

Regulatory publications

accountsBalances

/stet/psd2/v1/accounts/{accountResourceId}/balances
GET – accountsBalancesGet

Résumé

Retrieval of an account balances report (AISP)

Description

Description
This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification

• The ASPSP must provide at least the accounting balance on the account.
• The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible.
• Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
• The TPP has previously retrieved the list of available accounts for the PSU

Business flow
The AISP requests the ASPSP on one of the PSU’s accounts. The ASPSP answers by providing a list of balances on this account.

• The ASPSP must provide at least the accounting balance on the account.
• The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible.
• Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.

Scopes

• aisp
• piisp
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

accounts

/stet/psd2/v1/accounts
GET – accountsGet

Résumé

Retrieval of the PSU accounts (AISP)

Description

Description
This call returns all payment accounts that are relevant the PSU on behalf of whom the AISP is connected. Thanks to HYPERMEDIA, each account is returned with the links aiming to ease access to the relevant transactions and balances. The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role.
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

Business Flow
The TPP sends a request to the ASPSP for retrieving the list of the PSU payment accounts. The ASPSP computes the relevant PSU accounts and builds the answer as an accounts list. The result may be subject to pagination in order to avoid an excessive result set. Each payment account will be provided with its characteristics.

Scopes

• aisp
• extended_transaction_history
• piisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

accountsTransactions

/stet/psd2/v1/accounts/{accountResourceId}/transactions
GET – accountsTransactionsGet

Résumé

Retrieval of an account transaction set (AISP)

Description

Description
This call returns transactions for an account for a given PSU account that is specified by the AISP through an account resource identification. The request may use some filter parameter in order to restrict the query

• on a given imputation date range
• past a given incremental technical identification

The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) is any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
• The TPP has previously retrieved the list of available accounts for the PSU

Business flow
The AISP requests the ASPSP on one of the PSU’s accounts. It may specify some selection criteria. The ASPSP answers by a set of transactions that matches the query. The result may be subject to pagination in order to avoid an excessive result set.

Scopes

• aisp
• extended_transaction_history
• piisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

consents

/stet/psd2/v1/consents
PUT – consentsPut

Résumé

Forwarding the PSU consent (AISP)

Description

Description
In the mixed detailed consent on accounts

• the AISP captures the consent of the PSU
• then it forwards this consent to the ASPSP

This consent replaces any prior consent that was previously sent by the AISP.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role.
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

Business Flow
The PSU specifies to the AISP which of his/her accounts will be accessible and which functionalities should be available. The AISP forwards these settings to the ASPSP. The ASPSP answers by HTTP201 return code.

Scopes

• aisp
• piisp
• extended_transaction_history

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

fundsConfirmations

/stet/psd2/v1/funds-confirmations
POST – fundsConfirmationsPost

Résumé

Payment coverage check request (PIISP)

Description

Description
The PIISP can ask an ASPSP to check if a given amount can be covered by the liquidity that is available on a PSU cash account or payment card.

Prerequisites

• The TPP has been registered by the Registration Authority for the PIISP role
• The TPP and the PSU have a contract that has been registered by the ASPSP
  • At this step, the ASPSP has delivered an “Authorization Code”, a “Resource Owner Password” or a “Client Credential” OAUTH2 access token to the TPP (cf. § 3.4.2).
  • Each ASPSP has to implement either the “Authorization Code”/”Resource Owner Password” or the “Client Credential” OAUTH2 access token model.
  • Doing this, it will edit the [security] section on this path in order to specify which model it has chosen
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU.

Business flow
The PIISP requests the ASPSP for a payment coverage check against either a bank account or a card primary identifier.
The ASPSP answers with a structure embedding the original request and the result as a Boolean.
Scopes

• extended_transaction_history
• piisp
• aisp

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

trustedBeneficiaries

/stet/psd2/v1/trusted-beneficiaries
GET – trustedBeneficiariesGet

Résumé

Retrieval of the trusted beneficiaries list (AISP)

Description

Description
This call returns all trusted beneficiaries that have been set by the PSU. Those beneficiaries can benefit from an SCA exemption during payment initiation. The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.

Prerequisites

• The TPP has been registered by the Registration Authority for the AISP role.
• The TPP and the PSU have a contract that has been enrolled by the ASPSP
  • At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
• The TPP and the ASPSP have successfully processed a mutual check and authentication
• The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
• The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

Business Flow
The AISP asks for the trusted beneficiaries list. The ASPSP answers with a list of beneficiary details structure.

Scopes

• piisp
• extended_transaction_history
• aisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

accountsBalances

/stet/psd2/v1.4.2/accounts/{accountResourceId}/balances
GET – accountsBalancesGet_v1.4.2

Résumé

Retrieval of an account balances report (AISP)

Description

This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification
– The TPP has been registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
– The TPP has previously retrieved the list of available accounts for the PSU
The AISP requests the ASPSP on one of the PSU’s accounts.
The ASPSP answers by providing a list of balances on this account. – The ASPSP must provide at least the accounting balance on the account. – The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible. – Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.

Scopes

• cbpii
• aisp
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

accounts

/stet/psd2/v1.4.2/accounts
GET – accountsGet_v1.4.2

Résumé

Retrieval of the PSU accounts (AISP)

Description

This call returns all payment accounts that are relevant the PSU on behalf of whom the AISP is connected.
Thanks to HYPERMEDIA, each account is returned with the links aiming to ease access to the relevant transactions and balances.
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results. – The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The TPP sends a request to the ASPSP for retrieving the list of the PSU payment accounts.
The ASPSP computes the relevant PSU accounts and builds the answer as an accounts list. The result may be subject to pagination in order to avoid an excessive result set. Each payment account will be provided with its characteristics.

Scopes

• extended_transaction_history
• cbpii
• aisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

accountsTransactions

/stet/psd2/v1.4.2/accounts/{accountResourceId}/transactions
GET – accountsTransactionsGet_v1.4.2

Résumé

Retrieval of an account transaction set (AISP)

Description

This call returns transactions for an account for a given PSU account that is specified by the AISP through an account resource identification.
The request may use some filter parameter in order to restrict the query – on a given imputation date range – past a given incremental technical identification
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.
– The TPP has been registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) is any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
– The TPP has previously retrieved the list of available accounts for the PSU
The AISP requests the ASPSP on one of the PSU’s accounts. It may specify some selection criteria.
The ASPSP answers by a set of transactions that matches the query. The result may be subject to pagination in order to avoid an excessive result set.
The default transaction set, in the absence of filter query parameter, has to be specified and documented by the implementation.

Scopes

• aisp
• cbpii
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

consents

/stet/psd2/v1.4.2/consents
PUT – consentsPut_v1.4.2

Résumé

Forwarding the PSU consent (AISP)

Description

In the mixed detailed consent on accounts
– the AISP captures the consent of the PSU
– then it forwards this consent to the ASPSP
This consent replaces any prior consent that was previously sent by the AISP.
– The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
The PSU specifies to the AISP which of his/her accounts will be accessible and which functionalities should be available.
The AISP forwards these settings to the ASPSP.
The ASPSP answers by HTTP201 return code.

Scopes

• aisp
• extended_transaction_history
• cbpii

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

endUserIdentity

/stet/psd2/v1.4.2/end-user-identity
GET – endUserIdentityGet_v1.4.2

Résumé

Retrieval of the identity of the end-user (AISP)

Description

This call returns the identity of the PSU (end-user).
– The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP. The AISP asks for the identity of the PSU. The ASPSP answers with the identity, i.e. first and last names of the end-user.

Scopes

• aisp
• extended_transaction_history
• cbpii

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

fundsConfirmations

/stet/psd2/v1.4.2/funds-confirmations
POST – fundsConfirmationsPost_v1.4.2

Résumé

Payment coverage check request (CBPII)

Description

The CBPII can ask an ASPSP to check if a given amount can be covered by the liquidity that is available on a PSU cash account or payment card.
– The TPP has been registered by the Registration Authority for the CBPII role
– The TPP and the PSU have a contract that has been registered by the ASPSP – At this step, the ASPSP has delivered an “Authorization Code”, a “Resource Owner Password” or a “Client Credential” OAUTH2 access token to the TPP (cf. § 3.4.2). – Each ASPSP has to implement either the “Authorization Code”/”Resource Owner Password” or the “Client Credential” OAUTH2 access token model. – Doing this, it will edit the [security] section on this path in order to specify which model it has chosen
– The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its OAUTH2 “Authorization Code”, “Resource Owner Password” or “Client Credential” access token which allows the ASPSP to identify the relevant PSU.
The CBPII requests the ASPSP for a payment coverage check against either a bank account or a card primary identifier.
The ASPSP answers with a structure embedding the original request and the result as a Boolean.

Scopes

• aisp
• cbpii
• extended_transaction_history

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

paymentRequestOConfirmation

/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}/o-confirmation
POST – paymentRequestOConfirmationPost_v1.4.2

Résumé

Confirmation of a payment request or a modification request using an OAUTH2 Authorization code grant (PISP)

Description

The PISP confirms one of the following requests or modifications:
– payment request on behalf of a merchant
– transfer request on behalf of the account’s owner
– standing-order request on behalf of the account’s owner
The ASPSP answers with a status of the relevant request and the subsequent Credit Transfer. – The TPP has been registered by the Registration Authority for the PISP role
– The TPP was provided with an OAUTH2 “Client Credential” access token by the ASPSP (cf. § 3.4.2).
– The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3) – The ASPSP has answered with a location link to the saved Payment Request (cf. § 4.5.4) – The TPP has retrieved the saved request in order to get the relevant resource Ids (cf. § 4.6).
– The PSU has been authenticated by the ASPSP through an OAUTH2 authorization code grant flow (REDIRECT approach) and the PISP got the relevant token
– The TPP and the ASPSP have successfully processed a mutual check and authentication – The TPP has presented its “OAUTH2 Authorization Code” access token Once the PSU has been authenticated through an OAUTH2 authorization code grant flow (REDIRECT approach), it is the due to the PISP to confirm the Request to the ASPSP in order to complete the process flow.
The ASPSP must wait for confirmation before executing the subsequent Credit Tranfer.

Scopes

• pisp
• aisp
• extended_transaction_history
• cbpii

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

trustedBeneficiaries

/stet/psd2/v1.4.2/trusted-beneficiaries
GET – trustedBeneficiariesGet_v1.4.2

Résumé

Retrieval of the trusted beneficiaries list (AISP)

Description

This call returns all trusted beneficiaries that have been set by the PSU.
Those beneficiaries can benefit from an SCA exemption during payment initiation.
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.
– The TPP has been registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that has been enrolled by the ASPSP – At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
– The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
The AISP asks for the trusted beneficiaries list.
The ASPSP answers with a list of beneficiary details structure.

Scopes

• cbpii
• aisp
• extended_transaction_history

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

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 suscribe to live with CBPII role,you have to provide QWAC and QSEAL certificates. Your CBPII role will be checked on the basis of informations get in the REGAFI.

Step 2 – Access authorization as a CBPII wich 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 wich Banque Populaire his accounts are based, you must ssubmit an access token retrieval request for this customer (see use case “Retrieve your access token”)

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

c)Our customer processes a strong authentication in this mobile interface wich 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 use case “Use and 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 use case “Refresh your access token”)

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

c) You get the refresh token for this customer

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 use case “Retrieve your access token”) and to provide the body parameters.

Request

post/funds-confirmations

Mandatory or facultative body parameters needed for this service call

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

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.

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 thru is 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, 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.

Indeed, the AISP must specify for its consuming APP, an 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
• 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, the Banque Populaire returns a response HTTP200 (OK) with data including the access_token.

See also see 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 suing 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 autentication (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 use case “Sandbox assembly”.

For more details on the data exchanged, see the use case “How to retrieve your OAUTH2 access token?”.

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 Polulaire 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) ;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 asks 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.

Exemple

You can find an example of this request in use case “Sandbox assembly”.

For more details on the data exchanged, see the use case “How to retrieve your OAUTH2 access token?”.

Verison history

This API is compliant with the STET standard (https://www.stet.eu/en/psd2/) in order to meet PSD2’s regulatory requirements. She has functionnal limitations wich are specific to the Banques Populaires.

As a reminder

• payment services directive (PSD2, (UE) 2015/2366 of 25/11/2015) went into force on january 13, 2018 : https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=celex%3A32015L2366
• it is supplemented by regulatory technical standards for strong customer authentication (RTS, Commission Delegated Regulation (EU) No 2018/389) and common and secure open standards of communication that will apply on september14, 2019. These standards are called RTS (Rules Technical Standards) : https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32018R0389

In France, the ordinance n° 2017-1252 of August 9, 2017 implements the PSD2 directive into the regulatory section of the monetary and financial code. This ordinance has been supplemented by two decrees (n° 2017-1313 and n° 2017-1314), and five orders that were published on August 31, 2017.

You can also refer to the virtual assistant about STET standard.

Important changes made since the first version delivered :

Roadmap

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

Limits

Functionnal 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 is used to address to the proper customer reference base.

Examples for this ASPSP :

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

• STET V1.4.2 POST https://www.16807.live.api.89c3.com/stet/psd2/v1.4.2/funds-confirmations (/!\ scope = cbpii)
• STET V1.6.2    POST https://www.16807.live.api.89c3.com/stet/psd2/v1.6.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 usd STET version).

In order to provide a service to users of payment 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 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 et QSEALC live certificates for the sandbox (if availabale for this ASPSP)

• QWAC and et 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 and the chatbot about the principle of eligibility.