Banque BCP – Funds Availability
How to reduce your risk ?
You, as a Third Party Provider (TPP), delivered to a customer a private labeled payment card linked to his bank account. The customer (PSU) is performing a transaction on an e-commerce site with it. The customer has previously given a consent to your entity as well as to his bank account holder.
Using API “Funds availability” setup by banks (ASPSP), you can request for real-time transaction amount coverage data authorized by the customer without asking for online banking credentials. You can then reduce your risk for overdue payments.
The bank will respond yes or no without any funds blockage corresponding to the transaction amount, neither any validation of this transaction.
The API resources can only be consumed if you have obtained the Card Based Payment Instrument Issuer (“CBPII” or “PIISP”) role status. This prerequisite is described in section “Eligibility”.
Once done, the overall process is as follows :
1- The customer agreed to use your service. He needs to select his ASPSP through your interface.
2- During the first set of data exchanges, you will request for an authorization token (and a refresh one). For this CBPII role, you need these tokens BEFORE consuming API resources. These tokens are issued by the ASPSP AFTER an identification and authorization process of the bank accound holder.
The ASPSP will :
- check your certificates and on-going agreement delivered by the Comptent Authority ;
- identify and authorize the customer using the “redirect” mode in order to issue the tokens.
3- If the above access is granted by the customer, you can then get these OAUTH2 tokens thru secure exchanges (see use case “Get your token“).
4- Whenever you present this token to the BPCE API gateway, you will be able to consume this API resources (see use case “Check funds availability“).
If the regulated 180-day token validity period expires, this process needs to be started again (see use case “Refresh your token“).
NB : any ASPSP can refuse the access to customer’s data fo rany justified reason (non compliant API call, blocked account, …).
Regulatory publications
Period | Document |
Availability of DSP2 APIs to date | Load the document |
Statistics Q1 2024 | Load the document |
Statistics Q4 2023 | Load the document |
Statistics Q3 2023 | Load the document |
Statistics Q2 2023 | Load the document |
Statistics Q1 2023 | Load the document |
Statistics Q4 2022 | Load the document |
Statistics Q3 2022 | Load the document |
Statistics Q2 2022 | Load the document |
Statistics Q1 2022 | Load the document |
Statistics Q4 2021 | Load the document |
Statistics Q3 2021 | Load the document |
Statistics Q2 2021 | Load the document |
Statistics Q1 2021 | Load the document |
Statistics Q4 2020 | Load the document |
Statistics Q3 2020 | Load the document |
Statistics Q2 2020 | Load the document |
Statistics Q1 2020 | Load the document |
Catégories
-
STETPSD2 V1.4.0
-
STETPSD2V142
/stet/psd2/v1/accounts/{accountResourceId}/balances
accountsBalance
ABSTRACT
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 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
- piisp
- extended_transaction_history
- aisp
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
200 | The ASPSP answers with a list of account balances |
204 | No Content |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
406 | Not Acceptable |
408 | Request Timeout |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1/accounts
accounts
ABSTRACT
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.
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
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
200 | The ASPSP return a PSU context – listing the accounts that have been made available to the AISP by the PSU and, – for each of these accounts, the further transactions that have been enabled by the PSU through HYPERMEDIA links. |
204 | No Content |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
406 | Not Acceptable |
408 | Request Timeout |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1/accounts/{accountResourceId}/transactions
accountsTransactions
ABSTRACT
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.
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
- extended_transaction_history
- piisp
- aisp
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
dateFrom | string query Inclusive minimal imputation date of the transactions. Transactions having an imputation date equal to this parameter are included within the result. |
dateTo | string query Exclusive maximal imputation date of the transactions. Transactions having an imputation date equal to this parameter are not included within the result. |
afterEntryReference | string query Specifies the value on which the result has to be computed. Only the transaction having a technical identification greater than this value must be included within the result |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
200 | Complete transactions response |
204 | No Content |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
406 | Not Acceptable |
408 | Request Timeout |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1/consents
consents
ABSTRACT
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.
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
- piisp
- aisp
- extended_transaction_history
PARAMETERS
access (required) | AccessRequestResource body parameters of a access request |
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
201 | Created |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
405 | Method Not Allowed |
406 | Not Acceptable |
408 | Request Timeout |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
INPUT
application/json
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1/funds-confirmations
fundsConfirmations
ABSTRACT
Payment coverage check request (PIISP)
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
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
paymentCoverage (required) | PaymentCoverageRequestResource body parameters of a payment coverage request |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Codes retour
200 | payment coverage request |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
405 | Method Not Allowed |
406 | Not Acceptable |
408 | Request Timeout |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
INPUT
application/json
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1/trusted-beneficiaries
trustedBeneficiaries
ABSTRACT
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.
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
- extended_transaction_history
- aisp
- piisp
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header http-signature of the request (cf. https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
200 | The ASPSP returns the list of whitelisted beneficiaries |
204 | No Content |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
406 | Not Acceptable |
429 | Too Many Requests |
500 | Internal Server Error |
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1.4.2/accounts/{accountResourceId}/balances
accountsBalances
ABSTRACT
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
- aisp
- extended_transaction_history
- cbpii
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Codes retour
200 | The ASPSP answers with a list of account balances |
204 | No content. |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
INPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1.4.2/accounts
accounts
ABSTRACT
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
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
200 | The ASPSP return a PSU context – listing the accounts that have been made available to the AISP by the PSU and, – for each of these accounts, the further transactions that have been enabled by the PSU through HYPERMEDIA links. |
204 | No content. |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1.4.2/accounts/{accountResourceId}/transactions
accountsTransactions
ABSTRACT
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
- extended_transaction_history
- cbpii
- aisp
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
dateFrom | string query Inclusive minimal imputation date of the transactions. Transactions having an imputation date equal to this parameter are included within the result. |
dateTo | string query Exclusive maximal imputation date of the transactions. Transactions having an imputation date equal to this parameter are not included within the result. |
entryReferenceFrom | string query Specifies the value on which the result has to be computed. Only the transaction having a technical identification greater than this value must be included within the result |
entryReferenceto | string query Specifies the value on which the result has to be computed. Only the transaction having a technical identification less than or equal to this value must be included within the result |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
200 | Complete transactions response |
204 | No content. |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1.4.2/consents
consents
ABSTRACT
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
- extended_transaction_history
- cbpii
- aisp
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
access (required) | Access body List of consents granted to the AISP by the PSU. |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
201 | Created |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
501 | Not Implemented. This code should be used when the entry point is implemented but cannot provide a result, given the context. When the entry point is not implemented at all, HTTP400 will be returned. |
503 | Service unavailable. |
INPUT
application/json
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1.4.2/end-user-identity
endUserIdentity
ABSTRACT
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
- cbpii
- extended_transaction_history
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
200 | The ASPSP returns the identity of the PSU |
204 | No content. |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
429 | Too many requests. |
500 | Internal server error. |
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1.4.2/funds-confirmations
fundsConfirmations
ABSTRACT
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
- cbpii
- extended_transaction_history
- aisp
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
paymentCoverage (required) | PaymentCoverageRequestResource body parameters of a payment coverage request |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
Codes retour
200 | payment coverage request |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
INPUT
application/json
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}/o-confirmation
paymentRequestOConfirmation
ABSTRACT
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
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
paymentRequestResourceId (required) | string path Identification of the Payment Request Resource |
confirmationRequest (required) | ConfirmationResource body Parameters needed for confirmation of the Payment Request, especially in “EMBEDDED-1-FACTOR” approach Even though there is no parameter, a Json (void) body structure must be provided. |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
200 | retrieval of the Payment Request enriched with the status report |
400 | Invalid status value |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
408 | Request Timeout. |
409 | Conflict. The request could not be completed due to a conflict with the current state of the target resource. |
429 | Too many requests. |
500 | Internal server error. |
503 | Service unavailable. |
INPUT
application/json
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
/stet/psd2/v1.4.2/trusted-beneficiaries
trustedBeneficiaries
ABSTRACT
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
PARAMETERS
Authorization (required) | string header Access token to be passed as a header |
PSU-IP-Address | string header IP address used by the PSU’s terminal when connecting to the TPP |
PSU-IP-Port | string header IP port used by the PSU’s terminal when connecting to the TPP |
PSU-HTTP-Method | string header Http method for the most relevant PSU’s terminal request to the TTP |
PSU-Date | string header Timestamp of the most relevant PSU’s terminal request to the TTP |
PSU-GEO-Location | string header Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP |
PSU-User-Agent | string header “User-Agent” header field sent by the PSU terminal when connecting to the TPP |
PSU-Referer | string header “Referer” header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that “referer” (incorrect spelling) is to be used. The correct spelling “referrer” can be used but might not be understood. |
PSU-Accept | string header “Accept” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Charset | string header “Accept-Charset” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Encoding | string header “Accept-Encoding” header field sent by the PSU terminal when connecting to the TPP |
PSU-Accept-Language | string header “Accept-Language” header field sent by the PSU terminal when connecting to the TPP |
PSU-Device-ID | string header UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device. |
Digest | string header Digest of the body |
Signature (required) | string header [http-signature of the request](https://datatracker.ietf.org/doc/draft-cavage-http-signatures/) The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate. |
X-Request-ID (required) | string header Correlation header to be set in a request and retrieved in the relevant response |
RETURN CODES
200 | The ASPSP returns the list of whitelisted beneficiaries |
204 | No content. |
401 | Unauthorized, authentication failure. |
403 | Forbidden, authentication successful but access to resource is not allowed. |
404 | Not found, no request available. |
405 | Method Not Allowed. |
406 | Not Acceptable. |
429 | Too many requests. |
500 | Internal server error. |
501 | Not Implemented. This code should be used when the entry point is implemented but cannot provide a result, given the context. When the entry point is not implemented at all, HTTP400 will be returned. |
OUTPUT
application/hal+json; charset=utf-8
application/json; charset=utf-8
AVAILABLE AUTHENTIFICATION
OAuth 2.0
Catégories
-
STETPSD2 V1.4.0
-
STETPSD2V142
Get your token
Access to PSD2 API is granted by the bank with an authorization token (or access token) issued using OAUTH2 standardized process.
How it works ?
See also STET V1.4.2.17 / Part I / section 3.4
1. The customer (PSU) provides the identity of the bank which holds his accounts (ASPSP) to the TPP.
2. The TPP initiates an OAUTH2 access token request sequence by redirecting the customer to the ASPSP’s authorization infrastructure using GET /authorize
See also STET V1.4.2.17 / Part I / section 3.4 1
3- ASPSP will :
- Identify and authenticate the PSU
- Check your role and validity of your eIDAS certificates and agreement
4- Once checks are done and correct, ASPS will redirect the PSU to your site using “call-back” URL given in the GET /authorize and to ASPSP for the Go Live process.
You will find in the response of this request a one-time-token with a short life period.
5- You can then call the ASPSP in order to request the OAUTH2 token (and refresh one) using POST /token with previously received data (incl’d the one-time-token).
Note : these /token requests for getting the Authorization Code flow shall be sent WITHOUT the « scope » parameter.
See also STET V1.4.2.17 / Part I / section 3.4
6- ASPSP will :
- Check your role and validity of your eIDAS certificates and agreement
- Checks the direct or indirect matching between the Authorization Number within the eIDAS certificate and the [client_id] value
7- Once checks are done and correct, ASPSP returns a response HTTP200 (OK) with data including the access token.
See also see STET V1.4.2.17 / Part I / section 3.4
8- As soon as you get the OAUTH2 access token (and a 180-day valid refresh token) issued by the bank, you can use it for each API request within the “Authorization” header, prefixed by the token type “Bearer”.
The [client_id] that is linked to the access token must directly or indirectly match with the Authorisation Number that is located within the TPP’s eIDAS certificate (QWAC).
If the access token is expired, the request will be rejected with HTTP401 with an error equal to “invalid_token”.
The request can be replayed once the access token has been refreshed suing the use case “Refresh your token“.
If your refresh token is about to expire, you will have to perform again all this process, meaning also redirect to ASPSP for customer’s strong autentication (PSU SCA).
For more details, see also OAUTH 2.0 Authorization Framework : https://tools.ietf.org/html/rfc6749#section-4.1
Exemple
You can find an example of this request in section “Test our API” and then “Use our sandbox“
Check Funds Availability
This service allows you to check if customer has enough funds available on his payment bank account (linked to your payment card based intrument) to cover the current transaction.
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
post /funds-confirmations
see STET V1.4.0 / Part II / section 4.6.4 page 23
Mandatory parameters
paymentCoverageRequestId : Id for the request
payee : merchant
instructedAmount : amount and currency of the transaction
accountId : Unique Id for the customer’s account
Result
The result given by the ASPSP is a boolean (YES or NO).
Example
Request
Post http://localhost:8080/v1/funds-confirmations
Body
{
“paymentCoverageRequestId” : “MyCoverage123456”, “instructedAmount” : { “currency” : “EUR”, “amount” : “12345” }, “accountId” : { “iban” : “YY13RDHN98392489481620896668799742” } } } |
Résultat
Status code : 200
Body
{
“request” : { “paymentCoverageRequestId” : “MyCoverage123456”, “instructedAmount” : { “currency” : “EUR”, “amount” : “12345” }, “accountId” : {“iban” : “YY13RDHN98392489481620896668799742” } }, “result” : true, “_links” : { “self” : { “href” : “v1/funds-confirmations” } } } |
see also STET V1.4.0 / Part III / section 6 page 12
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 |
Nominal case (funds are available) | PSU Persona : CLAIRE
Scope OAuth2 = piisp Amount < 459€ accountId :FR7617515900000800358074006 Currency : EUR Result :
|
Insufficient funds | PSU Persona : LEA
Prérequis : scope OAuth2 = piisp Amount > 4 179€ accountId : FR7613807008043001965405158 Currency : EUR Result :
|
Non authorized HTTP request using GET method | PSU Persona : LEA
Scope OAuth2 = piisp Result : HTTP code 405 => unauthorized method |
HTTP request with missing IBAN | PSU Persona : LEA
Scope OAuth2 = piisp Amount = 4 179€ accountId : FR7617515000920400430518020 Currency : EUR Result : HTTP code 400 => wrong request |
HTTP request with missing amount parameter | PSU Persona : LEA
Scope OAuth2 = piisp accountId : FR7617515000920400430518020 Result : HTTP code 400 => wrong request |
HTTP request with missing of incorrect currency | PSU Persona : CLAIRE
Scope OAuth2 = piisp Amount > 4 179€ accountId : FR7617515900000800358074006 Currency : USD Result : HTTP code 400 => wrong request |
HTTP request with a missing or incorrect transaction Id | PSU Persona : LEA
Scope OAuth2 = piisp Amount > 4 179€ Currency : EUR Result : HTTP code 400 => wrong request |
Refresh your token
Principle
The refresh token issued by the bank ASPSP is valid up to 180 days and needs to be renewed before it expires. Please also note that :
- Authorization and refresh tokens can be revoked at any moment ;
- If the Authorization token is revoked, then the refresh one is automatically revoked (and the other way round) ;
- The access token has a shorter life cycle (10 to 15min) on standalone device.
How it works ?
1. You request for a refresh token using POST /token
See also STET V1.4.0.47 / Part I / section 3.4.3.4 / page 25
2. ASPSP :
- Identifies and authenticates the TPP through the presented eIDAS certificate (QWAC)
- Checks the direct or indirect matching between the Authorization Number within the eIDAS certificate and the [client_id] value.
- Controls last PSU SCA date (< 180 jours).
3. If correct, ASPSP then answers through a HTTP200 (OK) that embeds a new autorization token and refresh token that can replace the previous one. You need to store safely these tokens.
4. ASPSP de facto revokes the previous refresh token :
- After timeout of the by-law specified delay between two SCAs ;
- After timeout of the ASPSP specified delay based on internal rules if any ;
- After reject of a request for insufficient scope in order to allow the AISP to request another token with the desired scope ;
- On request of a PSU wanting to revoke the TPP access on his/her account data.
Please also note that, as a TPP, you are able to ask for the revocation of the refresh token through a POST /revoke request.
See also STET V1.4.0 / Part I / section 3.4.3.5 / page 26
RFC 7009, cf. https://tools.ietf.org/html/rfc7009
Version history
This API is based on STET specifications in order to meet PSD2’s regulatory requirements. It takes into account the functional limitations specific to this ASPSP.
As a reminder
- payment services directive (PSD2, (UE) 2015/2366 of 25/11/2015) went into force on january 13, 2018:
- 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) :
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.
Our API version | STET standard version |
v1.0 | v1.4.0.47 |
v1.4.2 | v1.4.2.17 |
You can also refer to the FAQ section and the virtual assistant about STET specifications.
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
- security issue
- 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 |
v1.0 | v1.4.0.47 | Check funds availability | March 14, 2019 | September 14, 2019 |
v1.4.2 | v1.4.2.17 | Check funds availability | – | May 31, 2022 |
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.
Limits
Functional Limitation
The limitations of this PSD2 API are :
- Apply only to customers who suscribed online banking services
- Apply only to active and eligible online accessible payment accounts in euro currency
- Payment accounts from corporate segments are not yet available using this API
- Use the authentication with redirect only (Strong Customer Authentication required and handled by the bank APSPS)
- Acces to the customer’s informations will only be possible if he gave his consent previously
- Access to payment account is done only using IBAN as main parameter (and not your payment instrument)
- There will be no reservations of funds
Limitations on data
Live data will be accessible by using first our enrolment API “Register”.
Examples for this ASPSP :
- STET V1.4.0 POST https://www.12579.live.api.89c3.com/stet/psd2/v1/funds-confirmations (/!\ scope = piisp)
- STET V1.4.2 POST https://www.12579.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 used 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.
Once the agrement is granted, the Organisation Identifier (OID) given by the national authority has the following format :
PSDXX-YYYYYYYY-ZZZZZZZZ
“PSD” as 3 character legal person identity type reference
2 character ISO 3166 country code representing the NCA country
2-8 character NCA identifier (A-Z uppercase only, no separator)
PSP identifier (authorization number as specified by NCA)
This OID is very important for :
- identify yourself as a TPP in the STET API requests using the parameter “client_ID”
- to be included into the eIDAS certificates to be delivered to the bank (see below)
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 available 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.