![](https://developer.bpce.fr/app/uploads/2023/04/Paiement-mobile.png)
![](https://developer.bpce.fr/app/uploads/2023/04/Paiement-desktop01.png)
Caisse d’Epargne – Payment initiation (STET Standard V1.6.2)
How to initiate a payment ?
One of our customers makes a transaction on an e-commerce website or wants to initiate an account to account funds transfer.
Through this API “Payment initiation” available for ASPSP customers, the TPP can submit a real time payment initiation request which will result in final run in an “account to account” fund fransfert.
The connected customer will be requested by his bank to validate this transaction :
- He identifies and authenticates himself
- Then, he selects his bank account with a sufficient balance for the transaction amount
- Finally, the bank seals the transaction after the client has strongly authenticated himself to validate the transaction (some exemptions of this authentication process exist)
In addition, this version brings a single SCA flow if the debtor IBAN is forwarded in the PIS request :
- PSU verifies the displayed transaction information
- Finally, the bank seals the transaction after the client has strongly authenticated himself to validate the transaction (some exemptions of this authentication process exist)
The TPP can only use this API if you are a Payment Initiation Service Provider (“PISP”), this prerequisite is described in “Eligibility” use case.
Once this prerequisite has been filled, the global process will be the following one :
01- As a PISP provider, the TPP can propose funds transfer services to customers, or allow them to pay their purchases on an e-merchant web site you have contractualized with. Thru TPP interfaces, the customer selects in which bank (ASPSP) his account(s) is/are domiciliated and the TPP collects the transaction information (purchase amount, IBAN creditor, …).
02- During the first exchange with ASPSP’s infrastructures, the TPP will have to request an authorization token. As PISP, the TPP has to get this token BEFORE he accessing to PSD2 API resources. This token is generated by the ASPSP AFTER the TPP authenticates itself as a PISP service provider using eIDAS certificates.
As banking account holder, the ASPSP will verify if TPP certificates and national agreements are valid.
For this step, it is not necessary that we identify and authenticate the customer before generating the access token.
03- If all above checks are correct, TPP will be able, as a PISP, to get the OAUTH2 access token thru a secure exchange with BPCE API gateway platform (see “Get your token” use case).
04- By presenting this access token valid only for this transaction, TPP can then use resources of the “payment initiation” PSD2 API in order to :
- Initiate a payment/transfer (see “Send a PIS request” use case) ;
- Retrieve the status of a payment/transfer initiation request (see “Retrieve a PIS status“) ;
- Confirm a payment/transfer initiation request or a payment/transfer cancellation request (see “Confirm a PIS request”)
Consume the API
Prerequites
As TPP you have to be accredited by a national competent authority for this Payment Initiation Service Provider (“PISP”) role.
To access payment initiation API methods, you have to get an OAUTH2 access token provided by customer’s banking institution, obtained with your credentials.
You and the customer’s banking institution have successfully processed a mutual check and authentication (exchange of eIDAS QWAC certificates).
Then, you present your OAUTH2 access token to consume the payment initiation API’s methods.
Initiate a payment
Two use cases exist for a payment initiation :
1) The PISP forwards a payment request on behalf of a merchant : the customer (PSU) purchases goods or services on an e-commerce website (see top of the diagram below).
There is a contract between the merchant and the PISP.
The merchant forwards the requested payment characteristics to the PISP and redirects the customer to the PISP portal.
The PISP asks the customer in which banking institution (ASPSP) is located his account. Then he prepares the payment initiation request and sends this request to customer’s bank.
The beneficiary, as being the merchant, is set at the payment level.
2) The PISP forwards a transfer request on behalf of the owner of the account. The customer provides the PISP with all information requied for the transfer.
The PISP asks the customer in which banking institution (ASPSP) is located his account. Then he prepares the transfer request and sends this request to customer’s bank.
As a PISP, you forward to the ASPSP the request for payment initiation via the POST /paymentRequests method (see “Send a PIS request” use case).
The authentication method supported by the ASPSP is the REDIRECT approach :
1) The customer is redirected to identification screen proposed by his banking institution and he will enter his online banking identifier
If the PISP provides client’s online banking identifier directly in this request, this step will be skipped.
2) The customer is redirected to an authentication screen proposed by his banking institution in order to validate its identity
3) The customer is redirected to account selection screen proposed by his banking
If there is only one eligible IBAN, or if the PISP has already collected customer’s account to be debited and include it in the request, it will be automatically selected and displayed.
4) The customer selects (if applicable) and validates his account to be debited
5) The customer is redirected to a strong customer authentication (SCA) screen proposed by his banking institution to validate is payment/transfer
The process for this step depends on SCA method provided to the PSU by his bank institution (OTP SMS, secur’pass, etc.).
It also depends on PSU’s device (PC, mobile, smartphone, tablet).
6) The customer is redirected to a payment request confirmation screen proposed by his banking institution
7) The customer accepts or declines the transaction and is redirected to PISP app using call back URLs
In order to do so, the payment initiation request posted by the PISP includes one or two call back URLs :
The first one will be called by the customer’s banking institution if the payment request is processed without any error or rejection by the PSU (the PSU has given his consent for the payment)
The second one is to be used by the customer’s banking institution in case of processing error or rejection by the PSU (refusal of consent). This second URL is optional : the first url will be used if the second one is not transmitted
8) the TPP has to forwed a last confirmation request using POST /payment-requests/{paymentRequestResourceId}/confirmation for executing the PIS operation.
In addition, this version brings a single SCA flow if the debtor IBAN is forwarded in the PIS request :
1) The customer is redirected to a payment request confirmation screen proposed by his banking institution
2) The customer accepts or declines the transaction
3) The customer is redirected to an identification screen proposed by his banking institution in order to validate its identity
4) The customer is redirected to PISP app using call back URLs
5) the TPP has to forwed a last confirmation request using POST /payment-requests/{paymentRequestResourceId}/confirmation for executing the PIS operation
Retrieve the status of a payment of a payment request initiation
You may recover ay anytime the status of an initiation of payment via the method GET /paymentRequests (see “Retrieve a PIS status” use case).
This call allows you to retrieve all the payment initiation data enriched with the resource identifiers and the status of the payment initiation request and the payment it contains.
The data is available for 35 days.
Cancellation of a payment/transfer request
You may cancel an initiation of payment via the method PUT /paymentRequests (see “Cancel a PIS request“) effective as soon as it has been processed.
The SCA is performed using REDIRECT mode.
Confirmation of a payment request (PISP)
You may confirm a payment initiation request or payment initiation cancellation via the method POST /paymentRequests/{paymentRequestResourceId}/confirmation (see “Confirm a PIS request” use case).
There are no confirmations for a PIS cancellation.
Get yout token
Principle
Access to PSD2 API features is granted by the bank with an authorization token (or access token) issued using OAUTH2 standardized process.
How it works
See also STET / Part I
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
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.
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.
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
Example
You can find an example of this request in section “Test our API” and then “Sandbox“.
How to use the fallback mode ?
Principle
In order to comply with PSD2 regulations, banks available on this BPCE API developer portal have setup contingency measures in case of unplanned unavailability of the dedicated API interface.
The principle of this « fallback » solution is explained below:
This fallback mechanism meets PSD2 regulatory requirements (article 33/RTS). It can be used with the same conditions and prerequisites applicable for the dedicated API interface which are specified in the “Eligibility” use case.
Roadmap
Please do find below our estimated roadmap :
Features | Sandbox Deployment BPCE API Dev Portal & Sandbox | Live Deployment BPCE Live API Gateway |
Fallback (*) | Not applicable | Septembre 2019 |
(*) Main features :
- Use the same API dedicated interface endpoint. The list of our banking institutions and the possible values of <bkcode> are specified in the “Limitations” use case ;
- A parameter (header ‘fallback:1’ present or absent) managed directly by the TPP allows do differentiate any « Fallback » request from dedicated interface PSD2 API requests ;
- Use of same TPP eIDAS certificate (QWAC) to be presented for mutual TLS authentication ;
- Use the same PSU authentication procedure and means for accessing online banking services ;
- This fallback solution is always active, even so the dedicated interface API must be used systematically in first priority. Its usage is subject to strict conditions as described in Article 33 of RTS, and can’t be used as the main access for PSD2 features. It will be monitored as such and every abuse will be automatically reported to our national competent authority.
Example
- If PSD2 API are not available due to unplanned unavailability or systems breakdown (see RTS Art. 33), TPP should use the following request with <codetab>=17515 as an example :
POST https://www.17515.live.api.89c3.com/stet/psd2/oauth/token
with :
- its live eIDAS QWAC certificate
- fallback:”1″ parameter in the header
2. If all checks are successful, the TPP will receive in the header of the response with url online (allowing to access banking login web page) as well as the JWT token.
3. TPP can then apply its proprietary login process using PSU credentials.
For more details about POST request, see STET V1.4.0.47 / Part I / section 3.4.3.2 / page 22 or STET V1.4.2.17 / Part I / section 3.4.3
Note
Please note the following constraints which apply on this fallback mechanism :
- No re-use of the API dedicated interface context, neither any of 180-day validity access token generated for AISP role
- Only online internet banking features are used as a reference (excl’d mobile banking features) and are accessible thru the fallback mode. As an example, online banking doesn’t propose any e-commerce transactions to customers, so PISP could NOT propose this feature in fallback mode
- The user of payment services (PSU) must be connected to the TPP PSP app, so no AISP batch process is possible
- PSD2 also imposes a reinforcement of strong customer authentication (SCA) for accessing direct online banking services. Therefore fallback mechanism leverages on reinforced PSU online banking authentication procedures and means such as (non exhaustive list) :
- Soft token
- OTP SMS
- Physical token (corporate market)
Trigger App2pp feature
Introduction
This service allows you to activate automatically (without PSU action) the banking app on PSU smartphone for identification and authentification process.
Prerequisites
The PSU has to load and to use at leat once the latest retail banking mobile app (V6.4.0 and higher) available on Android and Apple app stores.
Note : PRO & ENT customer segments are not yet activated
The callback universal link (same principe as url callback) shall be definied in advance by the TPP :
- if this link/url already exists on our BPCE API gateways, there is nothing else to do
- otherwise the TPP shall declare it using our API Register
Our “Universal links” links have been declared on iOS & Android platforms. It is not worthwhile to access to them e. g. using https://www.<codetab>.live.api.caisse-epargne.fr/89C3api/accreditation/v2/.well-known/apple-app-site-association which sends back an error code.
Request
PSU banking app activation (with webview in the banking app) can be achieved in live production using a current STET API requests sequence (initiated by the TPP app on the same smartphone device) with the following endpoints (e.g. for Caisse d’Epargne :
- www.<codetab>.live.api.caisse-epargne.fr/stet/psd2/oauth/token
- App2App activated via ASPSP redirect url : www.<codetab>.live.api.caisse-epargne.fr/89C3api/accreditation/v2/…
Otherwise, the webview will be displayed on PSU smartphone web browser if :
- the banking app is not present on PSU device nor App2App compliant (not the latest version uploaded, see prerequisites)
or
- the other endpoint format is used www.<codetab>.live.api.89c3.com/stet/psd2/oauth/authorize (can be used as a backup in case of App2App problem)
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
-
STETPSD2V162
- get accountsBalances
- get accounts
- get accountsOverdrafts
- get accountsOwners
- get accountsTransactionsDetails
- get accountsTransactions
- put consents
- get endUserIdentity
- post fundsConfirmations
- post paymentRequestConfirmation
- put paymentRequest
- get paymentRequestTransactions
- get paymentRequests
- post paymentRequests
- get trustedBeneficiaries
/stet/psd2/v1.6.2/accounts/{accountResourceId}/balances
accountsBalances
Abstract
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
Prerequisites
– The TPP was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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 should provide at least one balance on the account. – For cash account, this balance should be the accounting balance (CACC) – For card transactions account, the accounting balance is meaningless and must be replaced by an other type of balance (OTHR).
– Case of no registered transaction on the account, this balance will have an amount equal to zero.
– 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
- pisp
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 |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return codes
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. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/accounts
accounts
Abstract
Retrieval of the PSU accounts (AISP)
Description
Description
This call returns all payment accounts that are relevant for 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 was registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that was 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
- cbpii
- extended_transaction_history
- pisp
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 |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return codes
200 | The ASPSP return a PSU context – listing the accounts that were made available to the AISP by the PSU and, – for each of these accounts, the further transactions that were 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.6.2/accounts/{accountResourceId}/overdrafts
accountsOverdrafts
Abstract
Retrieval of an account overdraft (AISP)
Description
Description
This call returns the overdrafts that can be used 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
Prerequisites
– The TPP was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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.
The ASPSP answers by the overdraft that can be applied.
Scopes
- aisp
- pisp
- 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 |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return codes
200 | Overdraft 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.6.2/accounts/{accountResourceId}/owners
accountsOwners
Abstract
Retrieval of an account owners (AISP)
Description
Description
This call returns the owners identities for a given PSU account that is specified by the AISP through an account resource identification.
This call cannot be used when the account is owned by a legal entity where the identity of this entity is directly available in the account structure (field [company]).
Prerequisites
– The TPP was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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.
The ASPSP answers by the identities of the account owners.
Scopes
- extended_transaction_history
- pisp
- aisp
- 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 |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
Return codes
200 | Account owners identities 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.6.2/accounts/{accountResourceId}/transactions/{transactionResourceId}/details
accountsTransactionsDetails
Abstract
Retrieval of transaction details (AISP)
Description
### Description
This call returns the details of a transaction from a given PSU account.
The AISP has to specified
– the account through an account resource identification
– the transaction through a transaction resource identifcation
### Prerequisites
– The TPP was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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 and the transactions from one given account
– A transaction includes a “details” hyperlink which indicates that detailed information is available for this transaction.
### Business flow
The AISP requests the ASPSP on one of the transactions.
The ASPSP answers by the details on this transaction.
Scopes
- extended_transaction_history
- aisp
- cbpii
- pisp
Parameters
Authorization (required) | string header Access token to be passed as a header |
accountResourceId (required) | string path Identification of account resource to fetch |
transactionResourceId (required) | string path Identification of transaction 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. |
dateType | string query This parameter specifies the type of date on which [dateFrom] and [dateTo] apply. If not provided, the ASPSP will use its own default date type as specified in its implementation documentation. The implementation documentation must also specify which date types are supported. |
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 |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
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.6.2/accounts/{accountResourceId}/transactions
accountsTransactions
Abstract
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 was registered by the Registration Authority for the AISP role
– The TPP and the PSU have a contract that was 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.
– Case of no registered transaction on the account, this result will be an empty list.
The default transaction set, in the absence of filter query parameter, has to be specified and documented by the implementation.
The sort order of transaction might be specific to each ASPSP, due to each Information System constraints.
Scopes
- aisp
- cbpii
- pisp
- extended_transaction_history
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. |
dateType | string query This parameter specifies the type of date on which [dateFrom] and [dateTo] apply. If not provided, the ASPSP will use its own default date type as specified in its implementation documentation. The implementation documentation must also specify which date types are supported. |
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 |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
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.6.2/consents
consents
Abstract
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 was registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that was 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
- extended_transaction_history
- pisp
- aisp
- cbpii
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.6.2/end-user-identity
endUserIdentity
Abstract
Retrieval of the identity of the end-user (AISP)
Description
Description
This call returns the identity of the PSU (end-user).
Prerequisites
– The TPP was registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that was 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 identity of the PSU. The ASPSP answers with the identity, i.e. first and last names of the end-user.
Scopes
- extended_transaction_history
- cbpii
- pisp
- 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 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.6.2/funds-confirmations
fundsConfirmations
Abstract
Payment coverage check request (CBPII)
Description
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.
Prerequisites
– The TPP was registered by the Registration Authority for the CBPII role
– The TPP and the PSU have a contract that was 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.
### Business flow
The CBPII requests the ASPSP for a payment coverage check against either a bank account or a card primary identifier.
This request cannot handle exchange rate and must be specified with the relevant account currency.
The ASPSP answers with a structure embedding the original request and the result as a Boolean.
Scopes
- cbpii
- pisp
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 |
Return codes
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.6.2/payment-requests/{paymentRequestResourceId}/confirmation
paymentRequestConfirmation
Abstract
Confirmation of a payment request using an OAUTH2 Authorization code grant (PISP)
Description
### 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. ### Prerequisites
– The TPP was 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 was 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 was 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 ### Business flow
Once the PSU was 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.
Any further confirmation by the PISP on the same Payment-Request must be ignored.
Scopes
- cbpii
- pisp
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. 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.6.2/payment-requests/{paymentRequestResourceId}
paymentRequest
Abstract
Cancellation of a Payment/Transfer Request (PISP)
Description
Description
The PISP sent a Payment/Transfer Request through a POST command.
The ASPSP registered the Payment/Transfer Request, updated if necessary the relevant identifiers in order to avoid duplicates and returned the location of the updated Request.
The PISP got the Payment/Transfer Request that was updated with the resource identifiers, and eventually the status of the Payment/Transfer Request and the status of the subsequent credit transfer.
The PISP requests for the payment cancellation (global cancellation) or for some payment instructions cancellation (partial cancellation)
No other modification of the Payment/Transfer Request is allowed.
Prerequisites
– The TPP was 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 previously posted a Payment/Transfer Request which was saved by the ASPSP (cf. § 4.5.3) – The ASPSP answered with a location link to the saved Payment/Transfer Request (cf. § 4.5.4) – The PISP retrieved the saved Payment/Transfer Request (cf. § 4.5.4)
– The TPP and the ASPSP successfully processed a mutual check and authentication
– The TPP presented its “OAUTH2 Client Credential” access token.
– The TPP presented the payment/transfer request.
– The PSU was successfully authenticated. Business flow
# Payment/Transfer request cancellation circumstances
The cancellation of a Payment/Transfer request might be triggered by the PISP upon request of the PSU.
It can also be triggered by the PISP itself in case of error or fraud detection.
Since the consequence of the cancellation will be a rejection of the Payment/Transfer request globally or limited to some of its instructions, the modification of the payment request will focus on setting the relevant status to the value “CANC”.
This “CANC” status must however be explained through a reason code that can be set with the following values: | Reason | description |
| —— | ———– |
| DS02 | The PSU himsef/herself ordered the cancellation. |
| DUPL | The PISP requested the cancellation for a duplication of a previous Payment/Transfer request |
| FRAD | The PISP requested the cancellation for fraudulent origin of the Payment/Transfer request |
| TECH | The PISP requested the cancellation for a technical issue on its side | #### Payment/Transfer request cancellation level
– Case of a payment with multiple instructions or a standing order, the PISP asks to cancel the whole Payment/Transfer or Standing Order Request including all non-executed payment instructions by setting the [paymentInformationStatus] and the relevant [statusReasonInformation] at payment level.
– Case of a payment with multiple instructions, the PISP asks to cancel one or several payment instructions by setting the [transactionStatus] and the relevant [statusReasonInformation] at each relevant instruction level. The cancellation request might need a PSU authentication before committing, especially when the request is PSU-driven. In other cases, the ASPSP may consider that a PSU authentication is irrelevant.
In order to meet all possibilities, the cancellation request must nevertheless include:
– The specification of the authentication approaches that are supported by the PISP (any combination of “REDIRECT” and “DECOUPLED” values).
– In case of possible REDIRECT or DECOUPLED authentication approach, one or two call-back URLs to be used by the ASPSP at the finalisation of the authentication and consent process : – The first call-back URL will be called by the ASPSP if the Transfer Request is processed without any error or rejection by the PSU – The second call-back URL is to be used by the ASPSP in case of processing error or rejection by the PSU. Since this second URL is optional, the PISP might not provide it. In this case, the ASPSP will use the same URL for any processing result. – Both call-back URLS must be used in a TLS-secured request.
– In case of possible “DECOUPLED” approach, a PSU identifier that can be processed by the ASPSP for PSU recognition. – The ASPSP saves the updated Payment/Transfer Request and answers to the PISP. The answer embeds – The specification of the chosen authentication approach taking into account both the PISP and the PSU capabilities. – In case of chosen REDIRECT authentication approach, the URL to be used by the PISP for redirecting the PSU in order to perform an authentication. Case of the PSU neither gives nor denies his/her consent, the Cancellation Request shall expire and is then rejected to the PISP. The expiration delay is specified by each ASPSP.
If any modification of the payment request other than cancellation is applied by the PISP, the ASPSP must reject the request with HTTP403 without modifying the payment request resource. There is no need for the PISP to post a confirmation of the cancellation request.
Scopes
- cbpii
- pisp
Parameters
Authorization (required) | string header Access token to be passed as a header |
paymentRequestResourceId (required) | string path Identification of the Payment Request Resource |
paymentRequest (required) | PaymentRequestResource body ISO20022 based payment Initiation 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 |
Return codes
200 | The cancellation request was saved. The ASPSP may have to authenticate the PSU before committing the update. |
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. |
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
Ouput
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/payment-requests/{paymentRequestResourceId}/transactions
paymentRequestTransactions
Abstract
Retrieval of the Credit Transfert Transactions that were processed for a given payment request (PISP)
Description
Description
The PISP gets the execution history of a payment request.
This entry-point is an alternative to the retrieval of the history through the retrieval of the payment request.
So, each ASPSP may choose or not to implement this entry-point. Prerequisites
– The TPP was registered by the Registration Authority for the PISP role
– The TPP has previously posted a Standing Order Request which was 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 TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP was provided with an OAUTH2 “Client Credential” access token by the ASPSP (cf. § 3.4.2).
– The TPP presented its “OAUTH2 Client Credential” access token. ### Business flow
The PISP post the history request.
The ASPSP answers with the list of relevant transactions.
Scopes
- cbpii
- pisp
Parameters
Authorization (required) | string header Access token to be passed as a header |
paymentRequestResourceId (required) | string path Identification of the Payment Request Resource |
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. |
Output
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
/stet/psd2/v1.6.2/payment-requests/{paymentRequestResourceId}
paymentRequests
Abstract
Retrieval of a payment request (PISP)
Description
### Description
The following use cases can be applied:
– retrieval of a payment request on behalf of a merchant
– retrieval of a transfer request on behalf of the account’s owner
– retrieval of a standing-order request on behalf of the account’s owner The PISP has previously sent a Request through a POST command.
– The ASPSP has registered the Request, updated if necessary the relevant identifiers in order to avoid duplicates and returned the location of the updated Request.
– The PISP gets the Request that was updated with the resource identifiers, and eventually the status of the Payment/Transfer Request and the status of the subsequent credit transfer. ### Prerequisites
– The TPP was 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 was saved by the ASPSP (cf. § 4.5.3) – The ASPSP has answered with a location link to the saved Payment/Transfer Request (cf. § 4.5.4)
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its “OAUTH2 Client Credential” access token ### Business flow
The PISP asks to retrieve the Payment/Transfer Request that was saved by the ASPSP. The PISP uses the location link provided by the ASPSP in response of the posting of this request.
The ASPSP returns the previously posted Payment/Transfer Request which is enriched with:
– The resource identifiers given by the ASPSP
– The status information of the Payment Request and of the subsequent credit transfer
The status information must be available during at least 30 calendar days after the posting of the Payment Request. However, the ASPSP may increase this availability duration, based on its own rules.
Scopes
- pisp
- cbpii
Parameters
Authorization (required) | string header Access token to be passed as a header |
paymentRequestResourceId (required) | string path Identification of the Payment Request Resource |
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 previously posted Payment Request |
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.6.2/payment-requests
paymentRequests
Abstract
Payment request initiation (PISP)
Description
### Description
The following use cases can be applied:
– 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
#### Data content
A payment request or a transfer request might embed several payment instructions having
– one single execution date or multiple execution dates – case of one single execution date, this date must be set at the payment level – case of multiple execution dates, those dates must be set at each payment instruction level
– one single beneficiary or multiple beneficiaries – case of one single beneficiary, this beneficiary must be set at the payment level – case of multiple beneficiaries, those beneficiaries must be set at each payment instruction level
Having at the same time multiple beneficiaries and multiple execution date might not be a relevant business case, although it is technically allowed.
Each implementation will have to specify which business use cases are actually supported.
A standing order request must embed one single payment instruction and must address one single beneficiary.
– The beneficiary must be set at the payment level
– The standing order specific characteristics (start date, periodicity…) must be set at the instruction level Payment request can rely for execution on different payment instruments:
– SEPA Credit Transfer (SCT)
– Domestic Credit Transfer in a non-Euro-currency
– International payment
The following table indicates how to use the different fields, depending on the payment instrument: | Structure | SEPA payments | Domestic payments in non-euro currency | International payments |
| ——— | ————- | ————————————– | ———————- |
| PaymentTypeInformation/InstructionPriority (payment level) | “HIGH” for high-priority SCT, “NORM” for other SCT, Ignored for SCTInst | “HIGH” for high-priority CT, “NORM” or ignored for other CT | “HIGH” for high-priority payments, “NORM” or ignored for other payments |
| PaymentTypeInformation/ServiceLevel (payment level) | “SEPA” for SCT and SCTInst | ignored | ignored |
| PaymentTypeInformation/CategoryPurpose (payment level) | “CASH” for transfer request, “DVPM” for payment request on behalf of a merchant || “CORT” for generic international payments, “INTC” for transfers between two branches within the same company, “TREA” for treasury transfers |
| PaymentTypeInformation/LocalInstrument (payment level) | “INST” pour les SCTInst, otherwise ignored | Ignored or valued with ISO20022 external code ||
| RequestedExecutionDate (at transaction level) | Optional. if set by the PISP, it indicates the date on debit on the ordering party account. If not set by the PISP, this requests the ASPSP to execute the payment instruction as soon as possible. |||
| EndToEndIdentification (at transaction level) | Mandatory | Optional ||
| UltimateDebtor (at transaction level) | Optional |||
| UltimateCreditor (at transaction level) | Optional |||
| InstructedAmount (at transaction level) | Mandatory || Mandatory and exclusive use of one of these structures |
| EquivalentAmount (at transaction level) | Not used || Mandatory and exclusive use of one of these structures |
| ChargeBearer (at transaction level) | “SLEV” for SCT and SCTInst | “SLEV” or “SHAR” | “CRED”, “DEBT” or “SHAR” |
| Purpose (at transaction level) | Optional |||
| RegulatoryReportingCode (at transaction level) | Not used | Mandatory (possibly multiple values) |
| InstructionForCreditorAgent (at transaction level) | Not used || Optional (possibly multiple values) |
| RemittanceInformation | Mandatory. Structured or unstructured, depending on the local rules and constraints |||
| Debtor (at payment level) | Mandatory, 2 address lines only | Mandatory, 4 address lines only | Mandatory. Complete strustured address can be used. |
| DebtorAccount (at payment level) | Optional | Optional. Account currency may be specified ||
| DebtorAgent (at payment level) | Optional |||
| Creditor (at transaction level) | Mandatory, 2 address lines only | Mandatory, 4 address lines only | Mandatory. Complete strustured address can be used. Date and place of birth must be specified |
| CreditorAccount (at transaction level) | Mandatory | Mandatory. Account currency may be specified ||
| CreditorAgent (at transaction level) | Optional |||
| ClearingSystemId et ClearingSystemMemberId (at transaction level) | Not used || Optional |
| IntermediaryAgent et IntermediaryAgentAccount (at transaction level) | Not used | Optional || #### Prerequisites for all use cases
– The TPP was 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 and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its “OAUTH2 Client Credential” access token # Business flow
## Payment Request use case
The PISP forwards a payment request on behalf of a merchant.
The PSU buys some goods or services on an e-commerce website held by a merchant. Among other payment method, the merchant suggests the use of a PISP service. As there is obviously a contract between the merchant and the PISP, there is no need for the ASPSP to check the existence of such a contract between the PSU and this PISP to initiate the process.
Case of the PSU that chooses to use the PISP service:
– The merchant forwards the requested payment characteristics to the PISP and redirects the PSU to the PISP portal.
– The PISP requests from the PSU which ASPSP will be used.
– The PISP prepares the Payment Request and sends this request to the ASPSP.
– The Request can embed several payment instructions having different requested execution date.
– The beneficiary, as being the merchant, is set at the payment level. ##### Transfer Request use case The PISP forwards a transfer request on behalf of the owner of the account. – The PSU provides the PISP with all information needed for the transfer. – The PISP prepares the Transfer Request and sends this request to the relevant ASPSP that holds the debtor account. – The Request can embed several payment instructions having different beneficiaries. – The requested execution date, as being the same for all instructions, is set at the payment level. ##### Standing Order Request use case The PISP forwards a Standing Order request on behalf of the owner of the account. – The PSU provides the PISP with all information needed for the Standing Order. – The PISP prepares the Standing Order Request and sends this request to the relevant ASPSP that holds the debtor account. – The Request embeds one single payment instruction with – The requested execution date of the first occurrence – The requested execution frequency of the payment in order to compute further execution dates – An execution rule to handle cases when the computed execution dates cannot be processed (e.g. bank holydays) – An optional end date for closing the standing Order
Scopes
- cbpii
- pisp
Parameters
Authorization (required) | string header Access token to be passed as a header |
paymentRequest (required) | PaymentRequestResource body ISO20022 based payment Initiation 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 |
ui_locales | string query End-User’s preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. |
PSU-Workspace | string header Workspace to be used for processing the PSU authentication when confirming a PISP request. |
Return codes
201 | The request was created as a resource. The ASPSP must authenticate the PSU. |
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.6.2/trusted-beneficiaries
trustedBeneficiaries
Abstract
Retrieval of the trusted beneficiaries list (AISP)
Description
Description
This call returns all trusted beneficiaries that were 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 was registered by the Registration Authority for the AISP role.
– The TPP and the PSU have a contract that was 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
- pisp
- 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 |
workspace | string query Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token. |
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. |
Ouput
application/hal+json; charset=utf-8
application/json; charset=utf-8
Available authentification
OAuth 2.0
Catégories
-
STETPSD2V162
- get accountsBalances
- get accounts
- get accountsOverdrafts
- get accountsOwners
- get accountsTransactionsDetails
- get accountsTransactions
- put consents
- get endUserIdentity
- post fundsConfirmations
- post paymentRequestConfirmation
- put paymentRequest
- get paymentRequestTransactions
- get paymentRequests
- post paymentRequests
- get trustedBeneficiaries
Send a PIS request
Context
This call is used to send to the account-holding bank (ASPSP) of a customer (PAO) a request for payment initiation in order to debit the PAO account and to credit the account of the payment service user (PSU) for which the Payment Service Provider (PISP) is connected.
The initiation of single payment in euros is only accepted in our treatments. When submitting the request and if all the fields are correctly formatted, a response (HTTP 201) will be returned. This response will contain the resourceID of the payment initiation request, as well as the SCA Redirect authentication mode (sole mode available), the consent URL depending on the payer’s bank (urlconsent_approval_URL ) and nonce.Diffferent types of fund transfers operations are available (SCT Core immediate, diferred, recurring, Instant Payment PIS, bulk payment) –> see restrictions in the “Limits” use case.
WARNING : all requests won’t be cleared and settled as business rules apply and could reject the PIS (e.g. business and anti-fraud rules). A STET code is returned in these cases.
Prerequisites
In order to process this request, the TPP eligibility is mandatory (see “Eligibility” use case), and to obtain an OAUTH2 access token (see “Retrieve your access token” use case).
Request
The entry point depends on the bank code <bkcode>.
You need to insert the same <bkcode> parameter as the one used for requesting the access token.
As a reminder, the list of our banking institutions and the possible values of <bkcode> are specified in the “Limits” use case.
For example, the url to be used to access to a PSU from the Caisse d’Epargne Ile de France is :
- POST https://www.<bkcode>.live.api.89c3.com/stet/psd2/v1.6.2/payment-requests
Mandated parameters
Body structure and mandatory fields are described in the STET standard.
The parameters below must be setup at the following values :
- serviceLevel => mandatory and shall be filled with “SEPA”
- amount => mandatory and shall be filled with min/max values as applied on the online banking and they can be different per ASPSP and/or per requested processing (SCT CORE or INST) and/or per customer segment or contract
- currency => mandatory and shall be filled with “EUR”
- numberOfTransactions => mandatory and shall be filled with values as decribed below
- frequency ==> mandatory only for recurring SCT (values as decribed below)
- executionRule => optional “FWNG” (following = payment execution the next working day)
- localInstrument shall be setup at « INST » only for SEPA Instant Payment (SCT Inst) :
- fees can apply depending on ASPSP and customer segment
- beneficiary IBAN shall be elligible to accept SCT Inst
- remittanceInformation ==> mandatory and shall integrate “unstructured” label e.g. “remittanceInformation” : { “unstructured” : [ “test ” ] }
- “Iban“, “debtorAccount“, “creditorAccount” => a valid normalized IBAN issued by a credit institution (mandatory field : creditorAccount)
- chargeBearer field is mandatory (= “SLEV” in euro zone)
- successfulReportUrl => mandatory parameter for the REDIRECT mode, and it shall contain the redirect URL as well as pkce (code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) & code_challenge_method = S256) with “&” separator in the url (/!\ no “?” char)
- unsuccessfulReportUrl => if not filled, the data in “successfulReportUrl” will be used
- supplementaryData => mandatory and shall be filled with “REDIRECT”
- scaHint => mandatory field but the value will be ignored whatever value is set
- state => mandatory field (REDIRECT mode)
- endToEndId => mandatory field and shall not be empty
- categoryPurpose => mandatory for differenciating funds transfer from merchant-based operations (value “DVPM”) to non registered IBAN (value “CASH” or “SALA”), and allowing different business rules and SCA means to apply (a non secure enough SCA mean will not trigger the func transfer operation)
- requestedExecutionDate=> shall be greater than the current PIS request transaction datecreationDateTime
- creationDateTime => shall be compliant with ISO8601, the three regular expressions allowed are :
- YYYY-MM-DDTHH:MM:SS.SSS+HH:MM
- YYYY-MM-DDTHH:MM:SS.SSS+HHMM
- YYYY-MM-DDTHH:MM:SS.SSS
Note : char “Z” at the end means UTC
Example : 2019-11-12T00:00:00.000+02:00
Single SCA UX
If the PISP transmits to the ASPSP all the information necessary to initiate the payment, including the account number/IBAN of the account to be debited, ASPSPs supports a single SCA for a single payment initiation :
- Debtor IBAN (debtorAccount) only : a screen for PSU identification is still requested before the unique SCA (for dynamic linking)
- Debtor IBAN (debtorAccount) + PSU identification : no need ti identify the PSU before the unique SCA (for dynamic linking)
Cut-off for Immediate SCT Core
The CUT-OFF time means the deadline for fund transfer execution, and takes into account :
- internal processing (execution and clearing on the samle day)
- CUT-OFF from various interbank schemes (incl’d clearing house, see TARGET2 banking business days calendar and SCT rulebook)
In case of SEPA CREDIT TRANSFER (SCT), originator Banks are obliged to ensure that the amount of the SEPA Credit Transfer is credited to the account of the Beneficiary Bank within one Banking Business Day following the point in time of receipt of the Credit Transfer Instruction in accordance with the provisions of the Payment Services Directive.
A shorter execution time for SEPA Credit Transfers, knowing that operations may not be open for business on certain days of the year for the purpose of executing SEPA Credit Transfers.
It is not authorized to postpone the initial PSU order date except if it has been overriden. Execution time will be then reported to the following authorized date if it not a bank holiday. The execution process is triggered depending on the full timestamp of the PIS request.
For this ASPSP, CUT-OFF for SCT Core is fixed at 01:30 pm continental time (GMT+2 in summer, GMT+1 in winter).
creationDateTime | requestedExecutionDate | Résult | Actual Clearing date | Actual Settlement date |
Week day | ||||
Before 1:30 pm CET | D Day | OK | D Day | D Day if not a bank holiday, otherwise the following day if not a bank holiday |
As of 1:30 pm CET (incl’d) up to 11h59:59:999 pm | D Day | OK | D Day | D+1 Day if not a bank holiday, otherwise the following day if not a bank holiday |
Week -end or bank holiday | ||||
Before 1:30 pm CET | D Day | OK | D Day | Monday if not a bank holiday, otherwise the following day if not a bank holiday |
As of 1:30 pm CET (incl’d) up to 11h59:59:999 pm | D Day | OK | D Day | Monday if not a bank holiday, otherwise the following day if not a bank holiday |
Unitary SCT Core
The PIS request shall contain the numberOfTransactions field (mandatory) with value “1”.
Differed and recurrent SCT Core
The execution date (data requestedExecutionDate) for a differed SCT Core (or the first occurrence of a recurrent SCT Core) shall be setup at +72 hours like on online banking environment, otherwise it will be rejected.
For recurrent SCT, allowed frequencies (data frequency) are the following ones :
- weekly
- every two weeks
- monthy
- quaterly
- every six months
- yearly
The last settlement date (endDate) is mandatory ans shall be a valid date in future.
Bulk payment
This type of PIS request correspond to an operation from one corporate account to N creditor IBAN. If all execution criteria are filled, this will result in N fund transfer (different unitary amounts are allowed).
- numberOfTransactions => mandatory data and shall be valued between 2 (min) and 25 (max)
- categoryPurpose => mandatory data and shall be valued with “CASH” et “SALA”
- requestedExecutionDate=> mandatory data and shall be valued with the same date for the bulk payment (NO multi-date).
The PSU applies a single dynamic linking SCA for validating the bulk payment (a fisrt SCA may occur in order to display eligible accounts according to TPP requests).
If all conditions are met for a succesful operation :
- a unique debit (corresponding to the overvall bulk payment amount) will apply to PSU account
- the transactionStatus & paymentInformationStatus evolve in this case for the overall N unitary fund transfers
Conditions are NOT met in case of :
- If one of the unitary fund tranfer is rejected by the ASPSP before settlement –> the bulk payment is rejected and its PIS transactionStatus will be setup at RJCT » / paymentInformationStatus will be setup at « PART »
- If one of the unitary fund tranfer is rejected by the creditor bank –> PSU account will be credited from this unitary fund transfer amount, and its unitary PIS transactionStatus will be setup at « RJCT » / paymentInformationStatus will be « PART »
- If all unitary fund tranfers are rejected by the creditor bank –> PSU account will be credited from the global bulk payment amount, and all unitary fund transfer PIS transactionStatus will be « RJCT » / paymentInformationStatus will be setup at « RJCT »
Creditor IBAN control
A temporary control for NOT allowing PISP initiaitions has been added since December 7th, 2020 (alignment on direct access security features for funds transfer) :
- If the Creditor IBAN is NOT included in preregistered list done through the direct access
- AND if the field categoryPurpose = “CASH”
- AND if the SCA is NOT peformed by the PSU using the most secure authentication means (e.g. Sécur’Pass for retail PSU)
Error codes
Error type | HTTP code | Description | Reason |
Generic, bad structure | 400 | Bad request | error code : FF01 message : RJCT |
Wrong format for BIC | 400 | Bad request | error code : FF01 message : RJCT error : the field creditorAgent.bicFi bicFi-Code allocated to a financial institution by the ISO 9362 Registration Authority as described in ISO 9362 |
Wrong format for serviceLevel | 400 | Bad request | error code : FF01 message : RJCT error : value not one of declared Enum instance names: [SEPA, NURG] |
Wrong format for chargeBearer different from SLEV | 400 | Bad request | error code: FF01 message: RJCT error: value not one of declared Enum instance names: [SLEV] |
Wrong format for schemeName | 400 | Bad request | error code: FF01 message : RJCT error : the field creditor.privateId.schemeName schemeName-Possible values BANK,COID,SREN,DSRET,NIDN,OAUT,CPAN |
Wrong format for purpose | 400 | Bad request | error code: FF01 message: RJCT error: value not one of declared Enum instance names: [TRPT, CASH, CPKC, ACCT, COMC] |
Wrong format for categoryPurpose | 400 | Bad request | error code: FF01 message: RJCT error: value not one of declared Enum instance names: [CASH, DVPM] |
Wrong access token, authentication issue | 403 | Forbidden | |
Unknown request resource | 404 | Not Found | |
Wrong request, or request out of authorized scope | 405 | Method not allowed | |
Generic message | 500 | Internal server error | |
Duplicate request | 500 | Internal server error | error : Database insertion problem, duplicate unique key |
Confirm a PIS request
Use case
This mandated method allows the PISP to confirm a payment initiation request previously sent to the ASPSP for a given PSU using a POST/paymentRequests
The only implemented methode is POST /payment-requests/{paymentRequestResourceId}/confirmation also known as “reinforced” authentification mode. It has to be used following a PIS operations validated by the PSU, and not yet cleared.
Please note that a cancellation operation doesn’t need to be confirmed.
Prerequisites
In order to be able to use this request, the TPP needs to fulfill eligibility criterias as “PISP” role (see “Eligibility” section), and must get beforehand an OAuth access token (see use case “Overview” > “Retrieve a Token“).
The PISP has already sent a request which has been temporarly stored, and the ASPSP has given back a link to this saved request.
Request
The entry point depends on bank code parameter (<bkcode>) used for requesting the access token.
The list of current available bank institutions in sandbox is detailed below (see overall <bkcode> in “Limits” section).
For example, the following URL to be used in production is the following :
Mandated parameters
The mandated parameter is paymentRequestResourceId.
The structure of the body and mandated fields are described in STET specifications :
- nonce => challenge to be sent back by the TPP
- psuAuthenticationFactor => authentification factor
The TPP can extract the payment inititation information using the method GET /stet/psd2/v1.6.2/payment-requests/{paymentRequestResourceId} with :
- Data paymentInformationStatus shall be “ACSP“
- Data transactionStatus (in the creditTransferTransaction object) shall have the value “PDNG“
Returned Result
If all data are correct, a HTTP 200 will be returned, as well as the ressourceId & SCA authentication mode & consent URL (urlConsent_approval_URL) & nonce.
Please note that :
- data paymentRequestResourceId is included as a parameter inside consent URL sent back during the payment initiation
- same as nonce challenge parameters
Retrieve a PIS status
Use case
This method allows the PISP to obtain the status of a payment initiation request previously sent to the ASPSP for a given PSU through a POST /paymentRequests request.
Prerequisites
In order to process this request some eligibility prerequisites are needed, like to get an OAUTH2 access token beforehand (see “Get your token” use case).
The TPP has already sent a request that has been saved by the ASPSP and to which the ASPSP responded with a location link to the saved payment/transfer request.
Request
The entry point depends on the bank code <bkcode>.
You need to insert the same <bkcode> parameter as the one used for requesting the access token.
As a reminder, the list of our banking institutions and the possible values of <bkcode> are specified in the “Limits” use case.
For example, the url to be used to access to a PSU from the Caisse d’Epargne Ile de France is :
- GET https://www.<bkcode>.live.api.89c3.com/stet/psd2/v1.6.2/payment-requests/{paymentRequestResourceId}
Mandatory or facultative body parameters
Mandatory parameter paymentRequestResourceId: Identification of the payment request resource.
Returned result
When submitting the request and if all the data is correctly formatted, a response HTTP 200 will be returned.
This response will contain the payment initiation data enriched with the status of the initiation request and the associated payment.
The possible values for the status of the payment request are as follows (see STET specifications) :
Code | Description |
ACCO | AcceptedCustomerConfirmed : the customer has confirmed the payment request during his/her authentication. |
ACCP | AcceptedCustomerProfile : Preceding check of technical validation was successful. Customer profile check was also successful. |
ACSC | AcceptedSettlementCompleted : Settlement on the debtor’s account has been completed. |
ACSP | AcceptedSettlementInProcess : All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution. |
ACTC | AcceptedTechnicalValidation : Authentication and syntactical and semantical validation are successful. |
ACWC | AcceptedWithChange : Instruction is accepted but a change will be made, such as date or remittance not sent. |
ACWP | AcceptedWithoutPosting : Payment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account. |
CANC | Payment initiation has been successfully cancelled after having received a request for cancellation. |
PART | PartiallyAccepted : A number of transactions have been accepted, whereas another number of transactions have not yet achieved ‘accepted’ status. |
PATC | PartiallyAcceptedTechnicalCorrect |
RCVD | Received : Payment initiation has been received by the receiving agent. |
PDNG | Pending : Payment request or individual transaction included in the payment request is pending. Further checks and status update will be performed. |
RJCT | Rejected : Payment request has been rejected. |
The following table shows the possible values for the status of the payment initiation and the associated payment transaction :
Processing an initiation containing a payment | Result | paymentInformationStatus value | creditTransferTransactionStatus value |
Check and record the initiation request | OK | ACTC | – |
KO | RJTC | – | |
Consent | OK | ACCP | – |
KO | RJCT | – | |
Request for payment execution | OK | ACSP | PDNG if executed on the same day |
OK | ACSP | ACSP | |
KO | RJCT | RJCT | |
If the PSU doesn’t perform any action within 30 mns starting form the payment initiation reception | – | RJCT (NOAS reason) | RJCT (NOAS reason) |
Payment execution before clearing | – | ACSP | ACSP |
Single payment execution after clearing | OK | ACSC | ACSC |
KO | RJCT | RJCT | |
Recurrent payment execution after clearing | OK | ACSP | ACSP |
KO | RJCT | RJCT |
The following table shows the possible values following a status of the payment initiation cancellation :
Processing an initiation containing a payment | Result | paymentInformationStatus value | creditTransferTransactionStatus value |
Before cancellation request | – | ACTC/ACCP/ACSP | -/PDNG (ifpaymentInformationStatus = ACSP) |
Control of the cancellation request | OK | RJCT/RJCT/ACSP | -/PDNG (ifpaymentInformationStatus = ACSP) |
KO | ACTC/ACCP/ACSP | -/PDNG (ifpaymentInformationStatus = ACSP) | |
PSU Consent | OK | ACSP | PDNG |
KO | ACSP | PDNG | |
Execution of the cancellation | OK | CANC (DS02, DUPL, FRAD, TECH) | CANC (DS02, DUPL, FRAD, TECH) |
KO | ACSP | PDNG |
Availability of the debitor IBAN
The debitor IBAN is returned in the ASPSP response even if this data was not included in the PIS request sent by the TPP.
Error codes
Error type | HTTP code | Description | Reason |
Bad access token, authentication problem | 403 | Forbidden | |
Unknown request resource | 404 | Not Found | Unknown ressource |
Bad request or request outside the authorized scope | 405 | Method not allowed | |
Generic message | 500 | Internal server error | |
Duplicate query | 500 | Internal server error | error : Database insertion problem, duplicate unique key |
Cancel a PIS request
Use case
This method allows the PISP to cancel a payment initiation request previously sent to the ASPSP for a given PSU through a POST / paymentRequests request when the payment has not been executed yet.
Only SCT CORE differed operations in euros can be cancelled.
On the other way, and only for, a SCT operation initiated using PSD2 PISP API (whatever the version) can be cancelled by the PSU using his direct access.
Prerequisites
In order to be able to use this request, the TPP needs to fulfill eligibility criterias as “PISP” role (see “Eligibility” section), and muts get OAuth access token (see use case “Overview” > “Retrieve a Token“).
The PISP has already sent a PSD2 PIP V1.4.2 request which has been temporarly stored, the ASPSP has given back a link to this saved request.
In other words, to cancel a PIS operation shall be done using the same version used for the payment initiation.
Only differed and recurrent SCT can be cancelled.
Request
The entry point depends on the bank code <bkcode>.
You need to insert the same <bkcode> parameter as the one used for requesting the access token.
As a reminder, the list of our banking institutions and the possible values of <bkcode> are specified in the “Limits” use case.
For example, the url to be used to access to a PSU from the Caisse d’Epargne Ile de France is :
- PUT https://www.17515.live.api.89c3.com/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}
Mandatory or optional parameters in the request body
The mandated parameter is “paymentRequestResourceId” : identification of the PISP initiation to cancel.
Please refer to the STET specifications for the other format and optional parameters. Before sending the cancel request, the TPP can check previously the status of the PISP operation using GET /stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}. A PISP operation can be cancelled if the following data have the values as described below :
Pour savoir si un virement est éligible les informations suivantes doivent être valorisées dans la requête comme suit :
- paymentInformationStatus : “ACTC” / “ACCP” / “ACSP”
- transactionStatus (in “creditTransferTransaction” object) shall be “PDNG” (if paymentInformationStatus = “ACSP”), otherwise not filled
- serviceLevel : “SEPA”
- currency : “EUR”
- localInstrument : shall not be filled
- requestedExecutionDate : shall be at least the next day (D+1)
In order to be taken into accont, the cancel request sent to the ASPSP shall include the following data and values as described below (see API PSD2 STET_V1.4.2.17 Part 3 Interaction Examples p.23) :
- transactionStatus (in “creditTransferTransaction” object) : “RJCT”
- statusReasonInformation (in “creditTransferTransaction” object) : “DS02”
statusReasonInformation | Signification |
DS02 | Cancellation process requested by the PSU |
DUPL | Cancellation process requested by the PISP in case of redundant operation |
FRAD | Cancellation process requested by the PISP in case of fraudulent operation |
TECH | Cancellation process requested by the PISP in case of technical problem |
- All _links shall not be included
- “paymentRequest” parent label shall not be included as well as the final brace “}“.
The other data of the request shall be the same as the ones retrieved using the GET method.
In case of recurrent payment initiation
Such SCT recurrent payment initiation can be cancelled if it is still processed (ACSP) until the clearing of the last occurrence.
If all occurences have been cleared, csuch cancellation is not possible.
Result
If all data sent are correctly formatted, a HTTP 200 response will be returned, and will include PISP operation ressourceId, SCA mode (redirect), consent URL (urlconsent_approval_URL) and nounce.
Please note that the data “paymentRequestRessourceId” is included as a parameter in the URL consentement “consentApproval” sent back during the PISP initial operation (same for the nounce).
Error codes
Error | HTTP Code | Label | Reason |
Generic, wrong format (strcuture) | 400 | Bad request | error code : FF01 message : RJCT |
Wrong format (BIC) | 400 | Bad request | error code : FF01 message : RJCT error : le champ creditorAgent.bicFi bicFi-Code allocated to a financial institution by the ISO 9362 Registration Authority as described in ISO 9362 |
Wrong format (Service Level) | 400 | Bad request | error code : FF01 message : RJCT error : value not one of declared Enum instance names: [SEPA, NURG] |
Wrong format (chargeBearer other than SLEV) | 400 | Bad request | error code: FF01 message: RJCT error: value not one of declared Enum instance names: [SLEV] |
Wrong format (schemeName) | 400 | Bad request | error code: FF01 message : RJCT error : le champ creditor.privateId.schemeName schemeName-Possible values BANK,COID,SREN,DSRET,NIDN,OAUT,CPAN |
Wrong format (purpose) | 400 | Bad request | error code: FF01 message: RJCT error: value not one of declared Enum instance names: [TRPT, CASH, CPKC, ACCT, COMC] |
Wrong format (categoryPurpose) | 400 | Bad request | error code: FF01 message: RJCT error: value not one of declared Enum instance names: [CASH, DVPM] |
Wrong access token, TLS authentification problem | 403 | Forbidden | |
Request resource unknown | 404 | Not Found | |
Bad request or not allowed | 405 | Method not allowed | |
Generic | 500 | Internal server error |
Sandbox assembly
Introduction : detailed features of the Sandbox
You can use the BPCE API sandbox directly through your application by calling the payment initiation API of the BPCE-API platform (sandbox assembly).
In sandbox assembly, there are two types of requests:
- A first request to retrieve the authorization token (see “Get your token“) ;
- A second one to send a request to the payment initiation API (see “Send a PIS request” and “Retrieve a PIS status“).
Your application must request the AS (authentication server) to get an access token via its authentication key.
This access token will enable your application to submit the POST /payment-requests and the GET /payment-requests methods of the payment Initiation API.
You can perform a series of requests :
- Submit POST /payment-requests method to initiate a payment
- Then, submit GET /payment-requests/{paymentRequestResourceId} with the parameter paymentRequestResourceId got in response of the first request, to get the payment status
The data used in the tests are based on fictive persona (see “Test data” use case). This will enable you to choose specific profiles according to the tests.
The list of current available bank institutions for sandbox assembly for this API is detailed below (“bkcode” parameter used in URLs) :
Bank code | Bank name | Bank short name |
17515 | Caisse d’Epargne Ile De France | CEIDF |
Sequence stets to test access to the PISP API from your APP
Prerequisites
You must declare your APP on BPCE API portal (see “My apps” menu) and have your app registered using our API Register.
Please note that as a TPP, you must be accredited by any european competent authority (ACPR in France) for this Payment Initiation Service Provider role (“PISP”).
STEP #1 : Retrieve your access token
This call allows you to retrieve the access token from the institution’s authentication server, which is a prerequisite for each access to one of the payment initiation API methods. The description of this feature and the fields of the request are given in the “Get your token“.
The entry point for accessing to the sandbox assembly is : www.<bkcode>.sandbox.api.89c3.com
Request :
POST https://www.17515.sandbox.api.89C3.com/stet/psd2/oauth/token
Headers :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
Params :
client_id : PSDFR-ACPR-12345
grant_type : client_credentials
scope : pisp
Notes on parameters :
<bkcode> => bank code available in this environment : 17515 (Caisse d’Epargne Ile de France)
client_id : your agreement number as defined by your national competent authority. (PSDXX-YYYY-ZZZZZ)
grant_type => unchangeable = “client_credentials”
Response :
{
“access_token” : “firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz”,
“token_type” : “Bearer”,
“expires_in” : “3600”,
“scope” : “pisp”
}
Notes on parameters :
access_token => tokenCredential to transmit in the header authorization of payment initiation API requests, next to Bearer XX.
expires_in => period of validity of the token in seconds
STEP #2 : Send a payment initiation request
This call method post /payment-requests/ allows you to initiate a payment by asking the connected customer to give his consent for the payment.
The description of this feature and the fields of the request is given in the “Send a PIS request” use case.
Reminder: the authentication method supported by the bank is the REDIRECT authentication approach => the sequence of PSU identification and strong authentication (SCA) screens described below correspond to this authentication mode.
The entry point for accessing to the sandbox assembly is identical : www.<bankcode>.sandbox.api.89c3.com
Request :
POST https://www.17515.sandbox.api.89C3.com/stet/psd2/v1.6.2/payment-requests
Headers :
Authorization: Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Content-Type: application/json
Signature: keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<footprint-sha256>\“, algorithm=\”rsa-sha256\”, headers=\”(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\”, signature=\”LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\”
X-Request-ID : MyXrequestId123
Body :
{
“paymentInformationId” : “MyPmtInfld123”,
“creationDateTime” : “2019-07-22T09:25:22.527+02:00”,
“numberOfTransactions” : 1,
“debtorAgent” : {
“bicFi” : “CEPAFFRPP515”,
“name” : “CE Ile de France”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“15 Boulevard de la PI”,
“75001 Paris”
]
}
},
“initiatingParty” : {
“name” : “MyPispName”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“5 avenue Anatole France “,
“75007 PARIS”
]
},
“organisationId” : {
“identification” : “12FR5”,
“schemeName” : “COID”,
“issuer” : “ACPR”
}
},
“paymentTypeInformation” : {
“serviceLevel” : “SEPA”,
“categoryPurpose” : “DVPM”
},
“debtor” : {
“name” : “Marc “,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“512 rue de la coupe du monde”,
“94512 Charenton-le-Pont”
]
},
“privateId” : {
“identification” : “D0999990I0”,
“schemeName” : “BANK”,
“issuer” : “BICXYYTT512”
}
},
“debtorAccount” : {
“iban” : “FR7617515008043001965405255”
},
“beneficiary” : {
“creditor” : {
“name” : “myMerchant”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“Place Charles de Gaulle”,
“75008 PARIS”
]
},
“organisationId” : {
“identification” : “852126790”,
“schemeName” : “BANK”,
“issuer” : “FR”
}
},
“creditorAgent” : {
“bicFi” : “CCBPFRPP512”,
“name” : “B.P Grand Ouest”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“15 Boulevard de la Boutière”,
“CS 26858 35768 SAINT GREGOIRE CEDEX”
]
}
},
“creditorAccount” : {
“iban” : “FR7617515008043001965406128”
}
},
“purpose” : “COMC”,
“chargeBearer” : “SLEV”,
“requestedExecutionDate” : “2019-07-23T13:25:22.527+04:00”,
“creditTransferTransaction” : [
{
“paymentId” : {
“instructionId” : “MyInstrId123”,
“endToEndId” : “MyEndToEndId123”
},
“instructedAmount” : {
“currency” : “EUR”,
“amount” : “327.12”
},
“remittanceInformation” : [
“MyRemittanceInformation123”
]
}
],
“supplementaryData” : {
“acceptedAuthenticationApproach” : [
“REDIRECT”
],
“scaHint” : “scaExemption”,
“successfulReportUrl” : “https://extension.bpce.fr/calback.aspx&state=OK_12345&code_challenge_method=256&code_challenge=ABCD”
}
}
Notes on parameters :
Authorization : Bearer => access_token recovered for the tokenCredential
Following data must be unique, otherwise the request is rejected because of duplicate (the replay is not allowed):
– paymentInformationId ;
– instructionId ;
– endToEndId ;
– x-request-id.
debtor/privateId/identification => customer remote banking identifier : when filled, the identification screen of the customer is not displayed.
debtorAccount => customer’s IBAN : when it is filled, the only account selectable for the customer is the one that corresponds to this IBAN.
The implemented features may differ between the Banques Populaires and the Caisses d’Epargne (see “Send a PIS request” use case).
Response :
{
“appliedAuthenticationApproach” : “REDIRECT”,
“_links” : {
“consentApproval” : {
“href” : “https://www.17515.sandbox.api.89c3.com/89C3api/accreditation/v1/identificationPisp?paymentRequestResourceId=0000000a22-156688979900016807956016&nonce=s7m9KD6UerBT1F5gPL3m”,
“templated” : true
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 201 OK
Notes on parameters :
paymentRequestResourceId => identifier to pass to the GET /payment-requests request to recover the status of the payment initiation request.
appliedAuthenticationApproach” = “REDIRECT” => only allowed value
href => URL of the redirection page to the identification and authentication screens of the banking institution
nonce => technical anti-replay
currency => recovered from the body given as input
successfulReportUrl => recovered from the body given as input
unsuccessfulReportUrl => recovered from the body given as input
iban => recovered from the body given as input
creditorName => recovered from the body given as input
X-Request-ID => transmitted as input
STEP #3: Nominal sequence of PSU identification & SCA
Sequence of identification and strong authentication screens:
Using the URI returned in consentApproval, it is possible to play the sequence of screens.
1) The PSU is redirected to an identification screen presented by his ASPSP (redirection mode) in which he will enter his remote banking identifier.
Warning : only one call to this screen can be made
=> the “nonce” parameter in the URL that gives access to this screen can only be used once (any second call with this nonce will rejected)
=> if necessary, a new call to PaymentRequests is required to get a new token
The remote banking identifier of the customer is to be entered (see “Test data” use case for the data sets of the banking institution) :
For Caisses d’Epargne, Banque BCP, Crédit Coopératif & BTP Banque, if the customer is a professional or a corporate, he will have to enter is user number in addition to his remote banking identifier.
Note: If the PISP provides the remote banking identifier of the customer in its request (field “debtor/privateId/identification“), the first step is skipped & step 2) is automatically triggered.
2) The customer is redirected to a first authentication screen proposed by its ASPSP in order to validate his/her identity:
The SMS code for authentication is to be entered (see “Test data” use case for the data sets of the banking institution) :
This step depends on the strong authentication means proposed to the customer by the bank (SMS OTP, soft token, etc…).
It also depends on the equipment connected to the PISP APP used by the customer (PC or mobile / smartphone / tablet).
3) The customer is redirected to a screen where he will have to select its account to be debited.
IMPORTANT NOTE : If the PISP provides the IBAN of the customer to be debited in its request (field “debtorAccount“), only the corresponding account will be selectable and proposed to the customer :
Note: If the customer does not have an eligible PSD2 account, the request for payment initiation will not succeed and the customer will be redirected to your APP.
4) The customer selects and validates the account to be debited :
5) The customer is redirected to a second strong authentication screen proposed by his banking institution to validate his payment (dynamic linking).
Screens are identical to the strong authentication screen of step 2) to validate the customer’s identity.
The final decision whether or not to apply an authentication exemption is still at the discretion of the ASPSP as described in article 2 of the RTS of the DSP2.
For this ASPSP, exemptions are not possible for dynamic linking.
6) The PSU is redirected to a confirmation screen of the transaction proposed by its ASPSP.
Note: when the customer does not validate the payment initiation (or in the event of a timeout on the account selection page for example) the customer is redirected to the next page :
The customer is redirected to the PISP APP which provides in its first initiation request one or two call back URLs:
The first (successfulReportUrl) will be called by the banking institution in case the payment initiation request is processed and if the customer has given its consent for the payment.
A “code” parameter is added to this successfulReportUrl which is mandated to request the access token for the /confirmation method :
Example : https://<votre SuccessfulReportUrl>?code=GbmTn1ZZ76bibgvCRLxD4lNp8wMzkd
The second one (unsuccessfulReportUrl) will be used by the bank in case of refusal of consent or if the validation kinematics of the payment initiation is interrupted at one of its stages (example: timeout on the identification screen, on the account selection screen to be debited or the strong authentication screens). This second URL is optional : the first URL call back (successfulReportUrl) will be used if the second is not filled.
Sequence of the identification and strong authentication screens when the remote bank identifier of the customer (*) is transmitted in the request:
When the access identifier for the remote bank for the customer (debtor/privateId/identification field in the payment initiation request) is filled in, the call to the identification screen of the customer is not performed, cf. drawing below :
(*) for Caisses d’Epargne, Banque BCP, Crédit Coopératif et BTP Banque : the PSU segments PRO & ENT require having the PSU direct access identifier separated from the usage number by a “-“.
STEP #4 : Retrieve the Status of a payment initiation request (only available in live production)
This method get/payment-requests/{paymentRequestResourceId} allows you to retrieve all the payment initiation data enriched with the resource identifiers and the status of the payment initiation it contains.
The description of this feature and fields of the request is described in the use case “Retrieve a PIS status“. The data is accessible for 35 days.
For accessing to the sandbox assembly, the entry point is identical :
Request :
Headers :
Authorization: Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Content-Type: application/json
Signature: keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<footprint-sha256>\“, algorithm=\”rsa-sha256\”, headers=\”(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\”, signature=\”LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\”
X-Request-ID : MyXrequestId123
Notes on parameters :
Authorization:Bearer => access_token retrieved for tokenCredential.
x-request-id => must be the same as for the payment initiation request.
The paymentRequestResourceId is retrieved in response to the payment initiation request, when the payment initiation has been processed and the PSU has given its consent for the payment.
Response :
{
“paymentRequest” : {
“resourceId” : “0000000a22-146329369000016907660677”,
“paymentInformationId” : “MyPmtInfld123”,
“creationDateTime” : “2019-07-22T09:25:22.527+02:00”,
“numberOfTransactions” : 1,
“debtorAgent” : {
“bicFi” : “CEPAFRPP515512”,
“name” : “CE Ile de France”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“15 Boulevard de la PI”,
“75001 Paris”
]
}
},
“initiatingParty” : {
“name” : “MyPispName”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“5 avenue Anatole France “,
“75007 PARIS”
]
},
“organisationId” : {
“identification” : “12FR5”,
“schemeName” : “COID”,
“issuer” : “ACPR”
}
},
“paymentTypeInformation” : {
“serviceLevel” : “SEPA”,
“categoryPurpose” : “DVPM”
},
“debtor” : {
“name” : “Marc “,
“postalAddress”: {
“country” : “FR”,
“addressLine” : [
“512 rue de la coupe du monde”,
“94512 Charenton-le-Pont”
]
},
“privateId” : {
“identification” : “D0999990I0”,
“schemeName” : “BANK”,
“issuer” : “BICXYYTT512”
}
},
“debtorAccount” : {
“iban” : “FR76175157008043001965405255”
},
“beneficiary” : {
“creditorAgent” : {
“bicFi” : “CCBPFRPP512”,
“name” : “B.P Grand Ouest”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“15 Boulevard de la Boutière”,
“CS 26858 35768 SAINT GREGOIRE CEDEX”
]
}
},
“creditor” : {
“name” : “myMerchant”,
“postalAddress” : {
“country” : “FR”,
“addressLine”: [
“Place Charles de Gaulle”,
“75008 PARIS”
]
},
“organisationId” : {
“identification” : “852126790”,
“schemeName” : “BANK”,
“issuer” : “FR”
}
},
“creditorAccount” : {
“iban” : “FR761175153807008043001965406128”
}
},
“purpose” : “COMC”,
“chargeBearer” : “SLEV”,
“paymentInformationStatus” : “PDNG”,
“statusReasonInformation” : null,
“fundsAvailability” : null,
“booking”: null,
“requestedExecutionDate” : “2019-07-23T13:25:22.527+04:00”,
“creditTransferTransaction” : [
{
“paymentId” : {
“resourceId” : “0000000a22-146329369000016907660677”,
“instructionId” : “MyInstrId123”,
“endToEndId” : “MyEndToEndId123”
},
“instructedAmount” : {
“currency” : “EUR”,
“amount” : “327.12”
},
“remittanceInformation” : [
“MyRemittanceInformation123”
],
“transactionStatus” : “PDNG”
}
],
“supplementaryData” : {
“appliedAuthenticationApproach” : “REDIRECT”,
“scaHint” : “scaExemption”,
“successfulReportUrl” : “https://extension.bpce.fr/calback.aspx&state=OK-12345&code_challenge_method=256&code_challenge=ABCD”
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Notes on parameters :
resourceId => equals to paymentRequestResourceId
paymentInformationStatus => gives payment initiation status
transactionStatus => gives transaction status
X-Request-ID => transmitted as input
STEP #5 : Confirm payment initiation status (only available in live production, NOT in sandbox)
This mandated method POST/payment-requests/{paymentRequestResourceId}/confirmationallow to confirm a payment status for security reasons.
Please note that the method POST /payment-requests/{paymentRequestResourceId}/confirmation is not implemented.
The TPP needs to request a specific access token beforehand :
Request :
POST https://www.17515.live.api.89C3.com/stet/psd2/oauth/token
Headers :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
Body :
grant_type : authorization_code
client_id : the one generated if the TPP is enrolled using our API Register
code : code extracted from previous call in the successful URL at the end of STEP #3
code_verifier : depends on your PKCE data
redirect_uri: :predeclared uri communicated to ASPSP in the enrolment process
Response :
{
“access_token” : “secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs”,
“token_type” : “Bearer”,
“expires_in” : “3600”,
“refresh_token“: “1ji8KA9RJ5eXeJV1xKSDj1WDp8wwg3pRgDO2j0WhtbMsWz”,
“scope” : “pisp”,
“state“: “OK-12345”
}
Notes :
access_token => tokenCredential to be included in the next method Authorization field after the Bearer
It is now possible to use the confirmation method (in live production environment only)
POST https://www.17515.live.api.89C3.com/stet/psd2/v1.6.2/payment-requests/0000000a22-156688979900016807956016/confirmation
Headers :
Authorization: Bearer secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs
Content-Type: application/json
Signature: keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<footprint-sha256>\“, algorithm=\”rsa-sha256\”, headers=\”(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\”, signature=\”LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\”
X-Request-ID : MyXrequestId123
Body :
{
}
Authorization : Bearer => access_token extracted in the response of the previous POST /token method (the second one)Notes :
{paymentRequestResourceId} : same id used in previous GET /payments-requests
Response :
{ “paymentRequest” : {
“resourceId” : “0000000a22-156688979900016807956016”,
“paymentInformationId” : “MyPmtInfld123”,
“creationDateTime” : “2021-09-05T09:25:22.527+02:00”,
“numberOfTransactions” : 1,
“debtorAgent” : {
“bicFi” : “CEPAFRPP515512”,
“name” : “CE Ile de France”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“15 Boulevard de la PI”,
“75001 Paris”
]
}
},
“initiatingParty” : {
“name” : “Pisp Name”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“512 rue Reaumur”,
“75512 PARIS”
]
},
“organisationId” : {
“identification” : “12FR5”,
“schemeName” : “COID”,
“issuer” : “ACPR”
}
},
“paymentTypeInformation” : {
“serviceLevel” : “SEPA”,
“categoryPurpose” : “DVPM”
},
“debtor” : {
“name” : “Customer Name”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“512 rue Leclerc”,
“94512 Charenton-le-Pont”
]
},
“privateId” : {
“identification” : “D0999990I0”,
“schemeName” : “BANK”,
“issuer” : “BICXYYTT512”
}
},
“debtorAccount” : {
“iban” : “FR7617515000243021933556300”
},
“beneficiary” : {
“creditorAgent” : {
“bicFi” : “CCBPFRPP512”,
“name” : “Creditor Name”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“512 rue de la primaube”,
“12512 RODEZ”
]
}
},
“creditor” : {
“name” : “Amazon SA”,
“postalAddress” : {
“country” : “FR”,
“addressLine” : [
“512 avenue Maupassant”,
“75512 PARIS”
]
},
“organisationId” : {
“identification” : “852126790”,
“schemeName” : “BANK”,
“issuer” : “FR”
}
},
“creditorAccount” : {
“iban” : “FR7613825002000400000541718”
}
},
“purpose” : “COMC”,
“chargeBearer” : “SLEV”,
“paymentInformationStatus” : “PDNG”,
“statusReasonInformation” : null,
“fundsAvailability” : null,
“booking” : null,
“requestedExecutionDate” : “2021-09-06T14:10:10.109+01:00”,
“creditTransferTransaction” : [
{
“paymentId” : {
“resourceId” : “0000000a22-146329369000016907660677”,
“instructionId” : “instructionId 1630919339”,
“endToEndId” : “endToEndId 1630919339”
},
“instructedAmount” : {
“currency” : “EUR”,
“amount” : “2.41”
},
“remittanceInformation”: {
“unstructured”: [
“remittanceInformation01”
]
},
“transactionStatus” : “PDNG”
}
],
“supplementaryData” : {
“appliedAuthenticationApproach” : “REDIRECT”,
“scaHint” : “scaExemption”,
“successfulReportUrl” : “https://extension.bpce.fr/calback.aspx&state=OK-12345&code_challenge_method=256&code_challenge=ABCD”
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Test with persona
Introduction
As required by PSD2 regulation (see RTS Art. -30 (5)), we deliver a testing facility, including support, for connection and functional testing using non-real test data. These personna are gathered using banking segments (retail, corporate) and customer segmentation (student, young active, professionnal, retired, etc…).
Expected API input data are listed (PSU id, IBAN). PSU consent has already been recorded. These data included the accounting balance are static (no changes).
Please note that this test dataset will evolve overtime with additional profiles and data history (volume, depth). So stay informed and visit this dev portal regularly!
PSU ID & TEST DATA AS DESCRIBED BELOW CANNOT BE USED IN PRODUCTION LIVE ENVIRONMENT.
Persona
LEA SANDBOXA
- Student
- only one payment account
CLAIRE RECETTEB
- Young active and entrepreneur
- 2 payment accounts (1 individual, one professional)
GEORGES PERSONAC
- Active
- 1 joint payment account (Mr OR Mrs)
- more than 200 transactions on FR7617515000920400085945890
GILLES TESTUNID
- Retired
- 3 payment accounts (Mr, Mr OR Mrs, Mr AND Mrs)
Please note that in the assembly mode, you’ll have to enter OTP SMS = « 12345678 » for all persona whenever the authentication screen is proposed.
WARNING : NEW ID NUMBER
Persona | Segment | New
Id |
Bank code | IBAN | Payment account holder | PSU consent : balance/ Transactions / Identity | Balance | Currency |
LEA SANDBOXA | Individual | 9999999901 | 17515 | FR7617515000920400430518020 | LEA SANDBOXA | TRUE
TRUE FALSE |
-150.00 | EUR |
CLAIRE RECETTEB | Individual | 9999999902 | 17515 | FR7617515900000400358074026 | CLAIRE RECETTEB | TRUE
TRUE FALSE |
0.00 | EUR |
Professional / Entrepreneur individuel | 9999999902 | 17515 | FR7617515900000800358074006 | CLAIRE RECETTEB | TRUE
TRUE FALSE |
+23766.98 | EUR | |
GEORGES PERSONAC | Individual | 9999999903 | 17515 | FR7617515000920400085945890 | Mr et MME GEORGES PERSONAC | TRUE
TRUE FALSE |
+10.00 | EUR |
GILLES TESTUNID | Individual | 9999999904 | 17515 | FR7617515000920440878790811 | Mr GILLES TESTUNID | TRUE
TRUE FALSE |
+11880.30 | EUR |
9999999904 | 17515 | FR7617515000920402428687756 | Mr OU MME GILLES TESTUNID | TRUE
TRUE FALSE |
0.00 | EUR | ||
9999999905 | 17515 | FR7617515000920402428748381 | MR ET MME GILLES TESTUNID | TRUE
TRUE FALSE |
+5879.22 | EUR |
Version History
STET specifications
This REST-based API is compliant with the STET standard developed by the french market initiative (https://www.stet.eu/en/psd2/) in order to comply with PSD2 regulatory requirements. It takes into account functional limitations specific to BTP Banque savings banks network.
As a reminder :
- payment services directive (PSD2, (UE) 2015/2366 of 25/11/2015) went into force on january 13, 2018 : http://eur-lex.europa.eu/legal-content/FR/TXT/?uri=CELEX:32015L2366
- 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/FR/TXT/?toc=OJ%3AL%3A2018%3A069%3ATOC&uri=uriserv%3AOJ.L_.2018.069.01.0023.01.FRA
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 on August 31, 2017), and five orders that were published on August 31, 2017
Our API version | STET standard version |
v1.6.2 | v1.6.2.0 |
You can consult the virtual assistant on this portal.
Description of TPP support
According to Article 30 (5) of the RTS, a support for third-party providers is available.
This support can be joined via the form on this BPCE API portal (https://www.api.89c3.com/en/contact-us).
Responses are sent during office opening hours (09:00 – 18:00 Central European local Time) even so a 24h/7d monitoring process of our IT systems exists.
Its general principle is shown below, taking into account delays of Article 30 (4) of the RTS :
Release notes
Important changes made since the first release of this documentation was published :
Method(s) | Effective date | Description of the evolution |
All | November 16, 2022 | Alignment on PSD2 API STET v1.6.2.0 |
Roadmap
Deprecation process
According to API product life cycle, an API version can be deprecated (it 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 around the decommissioning process of a version N will be done at the release date of version N+1 through this portal / “roadmap” section.
Planning
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 roadmap :
Our API version | Features | Deployment date
Dev Portal & Sandbox |
Deployment date
BPCE Live API Gateway |
Deprecation date
BPCE Live API Gateway |
v1.6.2 | API version 1 :
API version 1.4.2 = API version 1 +
API version 1.6.2 = API version 1.4.2 +
|
November 16, 2022 | February 28, 2023 | To be announced |
v1.6.2 | Features above plus :
|
June, 2023 | June, 2023 | – |
Limits
Functional limits
General limits
- Apply only to eligible accessible online payment accounts (the determining criterion for the purposes of that categorisation lies in the ability to perform daily payment transactions from such accounts), and to PIS requests between two different accounts which are don’t belong to the same PSU ID / same ASPSP
- NO international currency transfers are available (just PIS requests in € are allowed)
- Use the authentication with redirect reinforced mode only (Strong Customer Authentication required and handled by the bank, which IS NOT an obstacle according to french national competent authority) & call for o-confirmation method
Note : TPP are not allowed to send to ASPSP the PSU credentials, and only ASPSP SCA redirect screens can be used (no embeding process as clarified by European Banking Authority based on articles PSD2 #95.5 & RTS #31)
- Manage payment initiation requests only in euro (not other currency allowed) either in :
- SCT CORE (immediate or difffered or recurrent) for all customer segments
- Bulk Payments (immediate from 1 debtor account to N creditor IBAN leading to N unitary operations with different amounts allowed) for corporate customers only for “CASH” & “SALA” PIS request category purposes
- Instant Payment for all customers segments
- The following methods are available :
- POST /payment-requests et POST /payment-requests/{paymentRequestResourceId}/confirmation
- GET /payment-requests/{paymentRequestResourceId}
- PUT /payment-requests/{paymentRequestResourceId} only for cancelling a unitary SCT Core deferred or recurring
- BIC is mandatory only for PIS in non eurozone (still in euro currency)
- Cancellation of PIS operations by the PSU is possible through his/her direct access (as well as via API before the same dead line applied for online banking environment)
- Different PIS requests having the identical parameters as an already executed one (same date, same debtor & creditor IBAN, same amount, …) will be rejected aligned on direct access behavior
- If the PSU doesn’t perform any action during 04 mns on redirect screens (or 30 mns overall), the PSU will be considered as disconnected and no redirection will be provided back to the TPP
- If the PSU has many PSD2 eligible payment accounts, it will be displayed to the customer a list of 10 accounts max for allowing the choice of the account to be debited
- creditor.name length is 32 char max
Customer segments limitations
- PART segment is retail segment (adult & autonomous customers, also includes “individual entrepreneur”)
- PRO segment gathers small companies
- ENT segment gathers medium to large corporations having online banking subscriptions (as CE Net Comptes or equivalent) allowing unitary funds transfers
Note : it doesn’t apply to legal guardians managing tutorships
Payment account limitations
- Payment accounts are those PSD2 eligible & available through the online banking / direct access
- Some business rules can apply (anti-fraud rules, …) and may reject fund tranfer operations before settlement
SCA limitations
- PART : [soft token Sécur’Pass] and/or [password + CAP reader] and/or [password + OTP SMS]
- PRO : [soft token Sécur’Pass] and/or [password + CAP reader] and/or [password + OTP SMS]
- ENT : [certificate on physical token] and/or [soft token Sécur’Pass] and/or [password + CAP reader] and/or [password + OTP SMS]
Note 1 : no SCA exemptions apply
Note 2 : PIS requests with “CASH” & “SALA” categoryPurpose will be rejected IF PSU SCA is not performed using Sécur’Pass (or the physical token for “PRO & ENT” customer segment) AND if the creditor IBAN is not registered before (> 72 hours) by PSU using direct access / online banking
Note 3 : the physical certificate won’t be proposed to the PSU when using a mobile device
Access to live data
According to PDS2 regulation, the data set available thru this dev portal, Try-it mode and sandbox are based on fictive data (or non-real ones). These data are described in the use case “Test our API“.
In order to access to live data, please use first our API Register (see product data sheet www.api.89c3.com/en/component/bpceportal/products/543/usecases/533).
IMPORTANT NOTE : a weekly slot is reserved for a programmed maintenance (all IT infrastructure incl’d backends and API gateways) Monday morning from midnight to 06:00 am CET, and could generate some perturbations during this period (as well as banking processes at the end of the day/month/quarter/year).
For live operations, the parameter “bank code” allows TPP to send API requests to the right ASPSP backend thru a dedicated « endpoint » www.<bank code>.live.api.89c3.com(or www.<bank code>.live.api.caisse-epargne.fr aligned on direct access domain name www.caisse-epargne.fr).
Once chosen, this entry point shall also be used for all subsequent requests.
bank code | ASPSP name | Bank short name | Available in Try-it and Sandbox | Available in production |
11315 | Caisse d’Epargne Provence Alpes Corse | CEPAC | – | Yes |
11425 | Caisse d’Epargne Normandie | CEN | – | Yes |
12135 | Caisse d’Epargne Bourgogne Franche-Comté | CEBFC | – | Yes |
14445 | Caisse d’Epargne Bretagne-Pays De Loire | CEBPL | – | Yes |
13135 | Caisse d’Epargne Midi-Pyrénées | CEMP | – | Yes |
13335 | Caisse d’Epargne Aquitaine Poitou-Charentes | CEAPC | – | Yes |
13485 | Caisse d’Epargne Languedoc-Roussillon | CELR | – | Yes |
13825 | Caisse d’Epargne Rhône Alpes | CERA | – | Yes |
14265 | Caisse d’Epargne Loire Drôme Ardèche | CELDA | – | Yes |
14505 | Caisse d’Epargne Loire-Centre | CELC | – | Yes |
17515 | Caisse d’Epargne Ile De France | CEIDF | Yes | Yes |
18315 | Caisse d’Epargne Côte d’Azur | CECAZ | – | Yes |
18715 | Caisse d’Epargne Auvergne et Limousin | CEPAL | – | Yes |
15135 | Caisse d’Epargne Grand Est Europe | CEGEE | – | Yes |
16275 | Caisse d’Epargne Hauts de France | CEHDF | – | Yes |
Eligibility
The “Payment initiation” API resources can only be used by Payment Service Providers (PSP) having a Payment Initiation Service Provider (PISP) role.
In order to provide a service to users of payment informations services under PSD2 directive, you must be a licenced PSP such as credit institution, electronic money institution, and payment institution. This status is delivered by the national competent authority 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 such agreement require rigorous procedures in order to give strong guarantees to the account informations services users. The forms are provided on the ACPR website : https://acpr.banque-france.fr/en/authorisation/banking-industry-procedures/all-forms
Once the agrement is granted, the Organisation Identifier (OID) given by the national authority has the following format :
PSDXX-YYYYYYYY-ZZZZZZZZ
“PSD” as 3 character legal person identity type reference
2 character ISO 3166 country code representing the NCA country
hyphen-minus “-” (0x2D (ASCII), U+002D (UTF-8)); and
2-8 character NCA identifier (A-Z uppercase only, no separator)
hyphen-minus “-” (0x2D (ASCII), U+002D (UTF-8)); andPSP identifier (authorization number as specified by NCA)
This OID is very important to identify yourself as a TPP :
- using STET API requests as OID is included in the parameter “client_ID”
- using mutual authentication (TLS) as OID is included in eIDAS certificates to be delivered to the bank (see below)
Please note that if you are using our API “Register”, an internal OID will be generated & shall be used for subsequent API requests.
You also need eIDAS (electronic IDentification And trust Services) compliant certificates delivered by a Qualified Certification Service Provider (QTSP, see list available on https://webgate.ec.europa.eu/tl-browser/#/).
In order to be able to consume PSD2 API published on our BPCE Portal, the TPP has to enroll its app and to use live certificates signed by a QTSP while sending API Register requests :
- a set of QWAC (for securing the TLS) and QSEALC (to be stored in our gateway) certificates for the sandbox
- another set of (for securing the TLS) and QSEALC (to be stored in our gateway) certificates for the live environment
A keyID shall also be provided with a correct STET format integrating the SHA256 certificate fingerprint after “_” char, see example STET Documentation Part 3: Interaction Examples / Signature : keyId=https://path.to/myQsealCertificate_612b4c7d103074b29e4c1ece1ef40bc575c0a87e.
Please embed only public keys. Controls on other data will be based on European Banking Association TPP register (https://euclid.eba.europa.eu/register/pir/disclaimer).
You can also consult the FAQ or our virtual assistant for any further question.