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.

Image

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}/o-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}/o-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 /paymentRequest (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.

1) The customer is redirected to an identification screen offered by its banking institution and in which it will enter its remote banking identifier.

2) The customer is redirected to a strong authentication screen offered by its banking institution to validate its identity.

3) The customer is redirected to a summary screen of the operation being canceled proposed by its bank.

4) The customer validates the cancellation of the transfer.

5) The customer is redirected to a confirmation screen for the operation offered by its bank.

6) The customer is redirected to the TPP PISP application.

The PISP provides one or two call back URLs with its cancellation request:

The first will be called by the banking establishment if the cancellation request is processed and if the customer has given its consent for this transaction cancellation.

The second URL will be used by the banking establishment in the event of refusal of consent or of a problem.

This second URL is optional: the first call back URL will be used if the second is left blank.

Confirmation of a payment request (PISP)

You may confirm a payment initiation request or payment initiation cancellation via the method POST /paymentRequests/{paymentRequestResourceId}/o-confirmation (see “Confirm a PIS request” use case).

There is no confirmation for a PIS cancellation.

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:

Image

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 :

(*) 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

1. 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.12579.live.api.89c3.com/stet/psd2/oauth/token
   
   with :
   
   - its live eIDAS QWAC certificate
   - fallback:”1″ parameter in the header
   
    

   Image

   

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)

Regulatory publications

Get your access token

Principle

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

Retrieval of access token sequence

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

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

See also STET V1.4.2.17 / Part I / section 3.4

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

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

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

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

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

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

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

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

See also STET V1.4.2.17 / Part I / section 3.4 

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

• Check your role (AISP or CBPII) and validity of your eIDAS certificates and agreement
• Checks the direct or indirect matching between the Authorization Number within the eIDAS certificate and the [client_id] value

7- Once checks are done and correct, the Banque Populaire returns a response HTTP200 (OK) with data including the access_token.

See also see STET V1.4.2.17 / Part I / section 3.4 

8- As soon as you get the OAuth2 access_token (and a 180-day valid refresh_token) issued by the bank, you can use it for each API request within the “Authorization” header, prefixed by the token type “Bearer”.

The [client_id] that is linked to the access token must directly or indirectly match with the Authorisation Number that is located within the TPP’s eIDAS certificate (QWAC).

If the access token is expired, the request will be rejected with HTTP401 with an error equal to “invalid_token”.

The request can be replayed once the access token has been refreshed suing the use case “Refresh your access token”.

If your refresh token is about to expire, you will have to perform again all this process “Get your access token” (see point 3 above), meaning also redirect to Banque Populaire for customer’s strong autentication (customer SCA).

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

Example 

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

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.

For the time being, 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 (HTPP 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.

Prerequisites

In order to process this request it’s needed to fill the eligibility (see “Eligibility” section), and to get the OAuth2 access token (see “Get 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 “Limitations” section.

For example, the url to be used to access to a PSU from the Banque Populaire Grand Ouest is :

• POST https://www.13807.live.api.89c3.com/stet/psd2/v1.4.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 => “SEPA”
• currency => “EUR” => NO international currency transfers are available
• requestedExecutionDate => shall be greater than transaction date and can’t be a week-end, a bank holiday or Target 2 closing day for SCT CORE payments (see calendar on https://www.ecb.europa.eu/paym/target/target2/profuse/calendar/html/index.en.htm)
  • For immediate SCT, il will be transformed to the next opening day
  • For recurring payment, the first occurrence shall not be the same day, or over 30 days
• numberOfTransactions => “1” for single payment initiation (incl’d for recurring ones)
• remittanceInformation shall integrate “unstructured” tag e.g. “remittanceInformation” : { “unstructured” : [ “test ” ] }
• executionRule => ignored for SCT CORE immediate and differed. For recurring payments, the only accepted value is “FWNG” (report to the next following day”). The execution date shall be accepted by the ASPSP (see requestedExecutionDate above)
• localInstrument shall be setup at « INST » only forSEPA Instant Payment (SCT Inst) available for all Banques Populaires ASPSP :
  • fees can apply depending on ASPSP and customer segment
  • beneficiary IBAN shall be elligible to accept SCT inst
  • for PRO / ENT customer segments, the PSU shall have their online banking SCT Inst flow contract updated in order to include debitor IBANs and creditor target countries.
• “Iban“, “debtorAccount“, “creditorAccount” => a valid normalized IBAN with UPPER case alphanumeric characters
• chargeBearer field is mandatory (= “SLEV” in euro zone)
• successfulReportUrl => mandated parameter for the REDIRECT mode, and it shall contain the redirect URL as well as pkce (code_challenge & code_challenge_method = S256) with “&” separator in the url (no “?” )
• unsuccessfulReportUrl => if not filled, the data in “successfulReportUrl” will be used
• supplementaryData => “REDIRECT”
• scaHint => field ignored whatever value is set => NO SCA exemptions are available
• categoryPurpose => mandatory as it allow to differenctiate funds transfert from merchant-based operations to non registered IBAN depending on SCA means used
• creationDateTime => 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

• “state” => mandated for REDIRECT mode
• beneficiary.creditor.name => limited to 35 length characters

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 (debtor.privateId.identification in UPPER case): no need to 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), there is a maximum execution time : 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.

CUT-OFF for SCT Core / execution on the same day is fixed at 11:00 am continental time (GMT+2 in summer, GMT+1 in winter).

CUT-OFF for SCT Core / execution & clearing on the next day is fixed at 05:00 pm continental time (GMT+2 in summer, GMT+1 in winter).

Recurring SCT Core

The data frequency is mandated only for SCT recurring PIS operations with one of the following values :

• MNTH (Monthly)
• QUTR (Quaterly)
• YEAR (Annual)

The data endDate (date of the last occurence) must also be valued in this case with a future date :

• requestedExecutionDate + n month if frequency = MNTH
• requestedExecutionDate + n quarters equency = QUTR
• requestedExecutionDate + n années si frequency = YEAR

Otherwise, it will be setup by the ASPSP at the max value requestedExecutionDate = 2099

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

Confirm a PIS request

Use case

This mandated method allows the PISP :

• Either to confirm a payment initiation request previously sent to the ASPSP for a given PSU through a POST /paymentRequests request
• Or to confirm the cancellation of a payment initiation request sent to the ASPSP for a given PSU through a POST /paymentRequests request, when the payment has not been executed yet

The only implemented methode is POST /payment-requests/{paymentRequestResourceId}/o-confirmation also known as “reinforced” authentification mode. It has to be used following a PIS operations validated by the PSU, and bnot yeat 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 muts get OAuth2 access token (see use case “Overview” > “Retrieve a Token“).

The PISP has already sent a request which has been temporarly stored, 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 “Limitations” section).

For example, the following URL to be used in production is the following :

• POST https://www.13807.live.api.89c3.com/stet/psd2/v1.4.2/payment-requests/{paymentRequestResourceId}/o-confirmation

Mandated parameters

The mandated parameter is paymentRequestResourceId.

The structure of the body and mandated fields are described in STET specifications :

• nounce => 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.4.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) & nounce.

Please note that :

• data paymentRequestResourceId is included as a paramter inside consent URL sent back during the payment initiation
• same as nounce

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 the OAuth2 access token (see “Get your access 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 “Limitations” section.

For example, the url to be used to access to a PSU from the Banque Populaire Grand Ouest is :

• GET https://www.13807.live.api.89c3.com/stet/psd2/v1.4.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 (HTPP 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 (values for STET version v1.4.2.17) :

The following table shows the possible values ​​for the status of the payment initiation and the associated payment transaction (values for STET version v1.4.1.17) :

The following table shows the possible values ​​following a status of the payment initiation cancellation (values for STET version v1.4.1.17) :

Availability of the debitor IBAN

Since the end of October 2020, 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

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 Banques Populaires, Banque de Savoie and Banque Palatine, a SCT operation initiated using PSD2 PISP API (whatever the version) can be cancelled using this request (in other words, this SCT operation can be cancelled thru another channel such as direct access “Cyber” or mobile app “Cyber mobile”)

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 OAuth2 access token (see use case  “Get your access 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 “Limitations” 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”

• 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

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 access 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 persona (see “Test data” section). 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) :

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 send us your QWAC and QSEALC test certificates public keys so we can :

• Declare your APP as a consumer application of the API ;
• Integrate your QWAC and QSEALC test certificates public keys in our infrastructure ;
• Retrieve and control your organizationId and your “PISP” role in our TPP registry.

Please note that as a TPP, you must be accredited (or in the on-going accreditation process) 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 “Retrieve your access token“.

The entry point for accessing to the sandbox assembly is : www.<bkcode>.sandbox.api.89c3.com

Request :

                POST https://www.13807.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 :

13807 (Banque Populaire Grand Ouest) ;

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.13807.sandbox.api.89C3.com/stet/psd2/v1.4.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”: “2021-09-05T09:25:22.527+02:00”, “numberOfTransactions”: 1, “requestedExecutionDate”: “2021-09-06T14:10:10.109+01:00”, “debtorAgent”: { “clearingSystemMemberId”: { “clearingSystemId”: “clearingSystemId”, “memberId”: “memberId” }, “bicFi”: “CCBPFRPP512”, “name”: “Cpy Name”, “postalAddress”: { “country”: “FR”, “addressLine”: [ “512 rue De Gaulle”, “85000 LRSY” ] } }, “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” ] } }, “beneficiary”: { “creditor”: { “name”: “Amazon SA”, “postalAddress”: { “country”: “FR”, “addressLine”: [ “512 avenue Maupassant”, “75512 PARIS” ] }, “organisationId”: { “identification”: “852126790”, “schemeName”: “BANK”, “issuer”: “FR” } }, “creditorAgent”: { “name”: “Creditor Name”, “bicFi”: “CCBPFRPP512”, “postalAddress”: { “country”: “FR”, “addressLine”: [ “512 rue de la primaube”, “12512 RODEZ” ] }, “clearingSystemMemberId”: { “clearingSystemId”: “clearingSystemId”, “memberId”: “memberId!” } }, “creditorAccount”: { “iban”: “FR7613825002000400000541718” } }, “chargeBearer”: “SLEV”, “creditTransferTransaction”: [ { “purpose”: “COMC”, “paymentId”: { “instructionId”: “instructionId 1630919339”, “endToEndId”: “endToEndId 1630919339” }, “instructedAmount”: { “currency”: “EUR”, “amount”: “2.41” }, “remittanceInformation”: { “unstructured” : [ “remittanceInformation01” ] } } ], “supplementaryData”: { “acceptedAuthenticationApproach”: [ “REDIRECT” ], “scaHint”: “scaExemption”, “successfulReportUrl”: https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK- 12345&code_challenge_method=S256&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).

Réponse :

{

“appliedAuthenticationApproach” : “REDIRECT”,

“_links” : {

“consentApproval” : {

“href” :”https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v2/identificationPisp?paymentRequestResourceId=00000000a22-156688979900016807956016&nonce=qJammuGI0OGCwznaZ0YO”,

“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

Image

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

Image

The remote banking identifier of the customer is to be entered (see “Test data” use case for the data sets of the banking institution), example for the persona “Marc” of the Banques Populaires :

Image

Note: If the PISP provides the remote banking identifier of the customer in its request (field “debtor/privateId/identification“), the following step is directly triggered.

 For Caisses d’Epargne, if the customer is a professional or a corporate, he will have to enter is user number in addition to his remote banking identifier.

Image

2) The customer is redirected to a first authentication screen proposed by its ASPSP in order to validate his/her identity:

Image

The SMS code for authentication is to be entered (see “Test data” use case for the data sets of the banking institution), example for the persona “Marc” of the Banques Populaires:

Image

This sequence depends on the strong authentication method 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.

Example for the persona “Marc” of the Banques Populaires who has 4 accounts, three of which are eligible for DSP2 payment initiations (see “Test data” section for the datasets of the banking institution):

Image

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 : example below for the persona Tech’n Co of the Banques Populaires.

Image

Note: If the customer does not have an account, the request for payment initiation will not succeed and the customer will be redirected to your APP. Example for the persona “Thomas” of the Banques Populaires.

Image

4) The customer selects and validates the account to be debited :

Image

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. So far, exemptions are not possible for the SCA step to validate the payments.

6) The PSU is redirected to a confirmation screen of the transaction proposed by its ASPSP.

Image

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 :

Image

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 /o-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 :

Image

(*) for Caisses d’Epargne, Banque BCP, Crédit Coopératif et BTP Banque PSU segments PRO & ENT : we require having the PSU subscription number separated fomr 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 :

GET https://www.13807.sandbox.api.89c3.com/stet/psd2/v1.4.2/payment-requests/0000000386-155532845000030007970322

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” : “CCBPFRPP512”,

“name” : “B.P Grand Ouest”,

“postalAddress” : {

“country” : “FR”,

“addressLine” : [

“15 Boulevard de la Boutière”,

“CS 26858 35768 SAINT GREGOIRE CEDEX”

]

}

},

“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” : “FR7613807008043001965405255”

},

“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” : “FR7613807008043001965406128”

}

},

“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}/o-confirmation  allow 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 :

Request :

POST https://www.13807.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 PSD2 Registration API

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.13807.live.api.89C3.com/stet/psd2/v1.4.2/payment-requests/0000000a22-156688979900016807956016/o-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)

{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” : “CCBPFRPP512”,

“name” : “Cpy Name”,

“postalAddress” : {

“country” : “FR”,

“addressLine” : [

“512 rue De Gaulle”,

“85000 LRSY”

]

}

},

“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” : “FR7613807000243021933556300”

},

“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 data

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.

This page presents the datasets for testing the API :

• Fictional customers, by customer segment (student, executive, business etc.) with either individual or professionial accounts that represent the populations of Banque Populaire’s customers (retail ; business ; corporate).
  • The individual is a natural person categorized as “capable adult”. The individual can also have activities within the framework of a sole proprietorship = a company directed by only one person, and which does not have a legal personality, although it is registered in the trades directory or in the Commercial Register and of Companies (RCS). Examples: craftsman or liberal profession. In this case, the IE is considered an individual.
  • The categories “professional” and “business” cover legal persons.
     
• Their accounts and deferred debit cards characteristics are described (single-account, multi-accounts, multi-bank accounts, presence of a debit card, account balance)
   
• Useful data expected in input by the API are enumerated (remote banking identifier, SMS code for authentication, IBAN)
   
• THESE PSU ID & TEST DATA CANNOT BE USED IN PRODUCTION LIVE ENVIRONMENT

Deprecation process

According to API product life cycle, an API version can be deprecated (means this API is not any more accessible on gateways and sandbox). 
An overlap period between two major API releases is provided as described below :

Image

The communication on the deprecation of a version N will be done at the release date of version N+1 through this Groupe BPCE API Store in the “roadmap” section of the related API.

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 :

Functional limits

General limits

• Apply only to authorized and eligible payment accounts (the determining criterion for the purposes of that categorisation lies in the ability to perform daily payment transactions from such accounts) that are accessible online (cf. PSD2 Directive text)
   
• 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 only single payment initiation requests in euro currency either in SCT CORE (immediate or differed or recurring/permanent) or Instant Payment for all customer segments of ASPSP Banques Populaires
   
• The following methods are available :
  • POST /paymentRequest
  • POST /paymentRequest/{paymentRequestResourceId}/o-confirmation)
  • GET/ paymentRequest and PUT /paymentRequest (only for differed PIPS) are the only ones available
     
• Field “chargeBearer” is mandatory as of POST /payment-requests method and must be valued to “SLEV”
   
• Field “categoryPurpose” is mandatory as of POST /payment-requests method
   
• Field “creditorAccount” is mandatory as of POST /payment-requests method
   
• Field “successfulReportUrl” is mandatory as of POST /payment-requests method
   
• If debtor account is included in PIS request, the PSU UX is reduced to one SCA (no SCA exemptions apply)
   
• Cancellation of differed PIS operations can only be made thru the API (before the same deadline applied for online banking environment)
   
• Creditor BIC is mandated
   
• If no PSU actions is performed 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
  
   

Customer segments limitations

• PART segment is retail segment (adult customer)
• PRO segment gathers small companies
• ENT segment gathers medium to large corporations
  
   

Payment account limitations

• Payment accounts are those available through the online banking
• Some business rules can apply and may limit fund tranfer operations (anti-fraud rules, …)
  
   

SCA limitations

• retail PSU : password + OTP SMS and/or CAP reader and/or soft token Sécur’Pass
• small professionals : hard token certificate and/or soft tokenSécur’Pass and/or password + CAP reader and/or password + OTP SMS
  
  Note : CASH PISP operations will be rejected if the PSU is not using Secur’Pass SCA and if the creditor IBAN is not registred by the PSU in his direct access.

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 section “How to test the API ?" / "Test data“.

In order to access to live data, please use first our PSD2 Registration API..

Please note that a weekly slot is reserved for a programmed maintenance (all IT infrastructure incl’d backends and API gateways) Sunday morning from 02:00 to 06:00 am, and could generate some perturbations during this period.

For live operations, the parameter “bankcode” allows TPP to send API requests to the right ASPSP backend thru a dedicated « endpoint » www.<bankcode>.live.api.89c3.com(or www.<bankcode>.live.api.banquepopulaire.fraligned on direct access domain name www.banquepopulaire.fr). Once chosen, this entry point shall also be used for all subsequent requests.

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 :

https://acpr.banque-france.fr/sites/default/files/medias/documents/jch_20180403_conference_securite_des_paiements.pdf

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))
   
• 2-8 character NCA identifier (A-Z uppercase only, no separator)
   
• hyphen-minus “-” (0x2D (ASCII), U+002D (UTF-8))
   
• PSP 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 “PSD2 Registration” API, 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 PSD2 Registration API 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

Note : in case of certificate renewal, and if the QTSP is different (or the same but using different root key elements), the TPP must advise our API support at least 2 months prior the change in order to be able to double check if the new certification authority is loaded on our infrastructure.

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 / section 6. AISP Use cases / 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.

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 Groupe BPCE API Store. 

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 :

Image

Release notes

Important changes made since the first version was delivered :