Initiate a payment
One of our customers is carrying out a transaction on an e-commerce site or wants to make a single or multiple transfer.
Via this “Payment Initiation” API provided by our bank, you can submit a payment initiation request in real time.
The connected customer will be asked by their bank to validate the transaction.
As part of a traditional course :
- The PSU identifies and authenticates itself;
- They then select the payment account with a sufficient minute balance for the amount of the transaction;
- Finally, the bank seals the transaction after the customer has re-authenticated strongly to validate the transaction.
As part of a seamless process, the debtor account data is transmitted in the payment initiation request:
- The PSU identifies itself if its identifier is not transmitted in the request;
- It then checks the operation information;
- Finally, the bank seals the transaction after the customer has strongly authenticated himself to validate the transaction.
This API can only be used by service providers acting as payment initiators (“PISPs”), this prerequisite being described in the “Eligibility” section.
Once this prerequisite has been met, the overall process is as follows:
1- The customer wants to use your services to make a single or multiple transfer, or select your service when asked by an e-merchant to pay for a purchase on the e-merchant’s site. They tell you the bank where their account is held via your interfaces.
2- During the first exchange with the account holder’s infrastructure, you will request an authorisation token. The basic principle is that, as a TPP PISP, you must obtain this token BEFORE using the API. This token is generated by the account holder (ASPSP) AFTER you have been identified.
As account holder, we will :
- Check your certificates and approvals.
For this API, it is not necessary for us to identify and strongly authenticate the customer in order to retrieve their consent and generate the access token.
3- If we have been able to verify your identity and approvals, you will then be able to retrieve an OAUTH2 access token via secure exchanges with the 89C3 API platform (see “Overview” > “Retrieve your token”).
4- By presenting this authorisation token, which is valid only for this transaction, you can then use the “payment initiation” API to :
- Initiate the payment (see “Use cases” > “Initiate a payment”);
- Retrieve the status of the payment initiation (see “Use cases” > “Retrieve the status of a payment initiation“);
- modify a payment initiation (see “Use cases” > “Cancel a payment initiation“)
- Confirm a payment initiation (see “Use cases” > “Confirm a payment initiation – confirmation method“).
Consume API
The description of the services offered below is purely functional. The technical aspects are listed in the “Use cases” sections, which are more detailed.
You should also be familiar with DSP2 terminology and the abbreviations used. You can also use the frequently asked questions (FAQ), the virtual assistant or the glossary.
Prerequisites
As a TPP, you must be accredited by the Autorité de Contrôle Prudentiel et de Résolution (ACPR) for the role of payment initiator (“PISP”).
To access the Payment Initiation API services, you need to retrieve an OAUTH2 access token issued by the PSU’s banking institution by querying it with your credentials.
As such, you must authenticate each other with the account holder (ASPSP) by exchanging eIDAS QWAC certificates.
You will then need to present your OAUTH2 access token in order to use the payment initiation API services.
Initiating a payment
There are two ways of using the Payment Initiation API:
1) The PISP requests payment on behalf of a merchant: the PSU customer buys goods or services on an e-commerce site (see top of diagram below).
There is a contract between the e-tailer and the PISP.
The e-merchant sends the requested payment details to the PISP and redirects the PSU customer to the PISP portal.
The PISP asks the PSU customer which bank he wishes to debit his account from. It then prepares the payment request and sends it to the customer’s bank.
The beneficiary (= the e-merchant) is indicated in the payment.
2) The PISP requests a single or multiple transfer on behalf of the PSU customer holding the account. The PSU provides the PISP with the information required for the transfer (see bottom of diagram below).
The PISP asks the PSU customer which bank he wishes to debit his account from. It then prepares the payment request and sends it to the PSU’s bank.
see STET specifications V1.6.2 / Part I / section 3.4.5.3 page 50
You send the payment initiation request using the POST /payment-requests method (see “Use cases” > “Initiating a payment”).
The authentication method supported by the bank is the reinforced REDIRECT mode:
1) The PSU is redirected to an identification screen provided by their bank, where they enter their remote banking identifier.
2) The PSU is redirected to an initial strong authentication screen proposed by their bank to validate their identity.
The kinematics of this stage depend on the strong authentication method made available to the PSU by the banking institution (SMS OTP, Secur’pass, etc.).
It also depends on the PSU equipment running the PISP application used by the PSU (PC or mobile/tablet).
3) The PSU is redirected to a screen for selecting the account to be debited proposed by their bank.
4) The PSU selects and validates the account to be debited.
5) The PSU is redirected to a second strong authentication screen proposed by their establishment to validate their payment.
The kinematics of this stage depend on the strong authentication method made available to the PSU by the banking institution (SMS OTP, Secur’pass, etc.).
It also depends on the PSU’s banking equipment on which the PSU application runs (PC or mobile/tablet).
6) The PSU is redirected to a transaction confirmation screen provided by their bank.
7) The PSU is redirected to the PISP application.
8) You send the payment initiation confirmation request using the POST method /payment-requests/{paymentRequestResourceId}/confirmation (see “Use cases” > “Confirm a payment initiation”), which triggers the bank to take the payment into account.
If the PISP provides the IBAN of the PSU to be debited in its request, the customer journey is simplified (“smooth PISP journey”):
1) The PSU is redirected to a confirmation screen for the single or multiple transfer in which only the account corresponding to the PSU’s IBAN is offered to the PSU.
3) The PSU validates the operation.
4) The PSU is redirected to an identification and strong authentication screen proposed by their establishment to validate their payment.
The kinematics of this stage depend on the strong authentication method made available to the PSU by the banking institution (SMS OTP, Secur’pass, etc.).
It also depends on the PSU’s banking equipment on which the PSU application runs (PC or mobile/tablet).
5) The PSU is redirected to a transaction confirmation screen provided by their bank.
6) The PSU is redirected to the PISP application.
7) You send the payment initiation confirmation request via the POST method /payment-requests/{paymentRequestResourceId}/confirmation (see “Use cases” > “Confirm a payment initiation”), which triggers the bank to take the payment into account.
When requesting initiation, the PISP provides one or two callback URLs:
- The first will be called by the bank if the initiation request is processed and the PSU has given its consent to the payment.
- The second callback URL will be used by the bank if consent is refused. This second URL is optional: the first call back URL will be used if the second is not filled in.
The PISP can fill in an indicator to indicate that it considers the payment request to be an SCA exemption case. The final decision on whether or not to apply an SCA remains with the PISP: to date, no exemption has been accepted among the cases of derogation from the PSU’s strong authentication requirement, if the general authentication requirements are met, as described in article 2 of the PSD2 RTS.
Recover the status of a payment initiation
You retrieve the status of a payment initiation using the GET /payment-requests/{paymentRequestResourceId} method (see “Use cases” > “Retrieving the status of a payment initiation“).
This call enables you to retrieve all the data from the payment initiation, enriched with the resourceId and the status of the initiation and the payment(s) it contains.
The data is accessible for 35 days.
Cancelling a Payment Initiation
For a deferred unit credit transfer or multipleSCT that has not yet been executed, or for a standing SCT unit credit transfer for which the last due date has not been reached, you cancel a payment initiation using the PUT /payment-requests/{paymentRequestResourceId} method (see “Use cases” > “Cancel a payment initiation“).
The authentication method supported by the bank is REDIRECT mode:
1) The PSU is redirected to an identification screen provided by their bank, where they enter their remote banking identifier.
2) The PSU is redirected to a strong authentication screen offered by their bank to validate their identity.
3) The PSU is redirected to a summary screen of the transaction being cancelled, as proposed by their bank.
4) The PSU validates the cancellation of the payment initiation.
5) The PSU is redirected to a transaction confirmation screen provided by their bank.
6) The PSU is redirected to the TPP PISP application.
When requesting cancellation, the PISP provides one or two callback URLs:
The first will be called by the bank if the cancellation request is processed and if the PSU has given its consent for the transaction to be cancelled.
The second URL will be used by the bank if consent is refused or if there is a problem. This second URL is optional: the first call back URL will be used if the second is not filled in.
Confirming a payment initiation
You confirm a payment initiation using the POST method /payment-requests/{paymentRequestResourceId}/confirmation, enhanced REDIRECT approach (see “Use cases” > “Confirm a payment initiation“).
However, the payment request cancellation confirmation service will not be supported. The cancellation will be effective as soon as the request has been accepted.
Sandbox assembly
Introduction – details of the sandbox functionality
The 89C3 API sandbox can be used directly via the TPP application by calling the “Payment Initiation” API of the 89C3 API platform.
In sandbox assembly, there are two types of call:
- The first is to retrieve the authorisation token (see “Overview” > “Retrieve your token”);
- The second is to make a call to the “Payment initiation” API (see the “Initiate a payment“, “Retrieve the status of a payment initiation“, “Confirm a payment initiation” and “Cancel a payment initiation” use cases).
Limitations in sandbox environments :
- The “Cancel payment initiation” use case is not fully testable in the sandbox environment because this method requires dynamic data cross-referencing, whereas our sandbox has static behaviour.
- Consequently, requests to cancel a payment initiation are accepted as soon as the format of the request is correct (the payment initiation identifier is assumed to exist).
Your application that uses the “Payment initiation” API in sandbox assembly will need to retrieve an access token via its authentication key from the AS (Authentication Server).
The TPP application using the “Payment initiation” API in sandbox assembly will need to retrieve an access token via its authentication key from the AS (Authentication Server).
The TPP application will be able to use the “POST /payment-requests“, “GET /payment-requests/{paymentRequestRessourceId}“, “POST /payment-requests/{paymentRequestRessourceId}/confirmation” and “PUT /payment-requests/{paymentRequestRessourceId}” methods thanks to its access token.
API method calls can be chained together:
- By executing the “POST /payment-requests” payment creation request.
- Then, by executing the request to retrieve the status of the payment “GET /payment-requests/{paymentRequestRessourceId} passing as a parameter the “paymentRequestRessourceId” retrieved from the result of the first request.
- Then, by executing the payment confirmation request “POST /payment-requests/{paymentRequestRessourceId}/confirmation“, passing the “paymentRequestRessourceId” retrieved from the result of the first request as a parameter.
- Then, by executing the “PUT /payment-requests/{paymentRequestResourceId}” request to cancel the payment, passing as parameters the “paymentRequestRessourceId” and the modified body retrieved from the result of the second request.
The data used to carry out the tests will come from the personas (see “How to test the API” > “Test our personas“), which will make it possible to choose specific profiles for the tests in order to gain a better understanding of the results obtained.
Prerequisites
The TPP must declare its APP in sandbox via our Register API.
Reminder: as a TPP, you must be accredited by one of the competent European national authorities (ACPR in France) for the role of payment initiator (“PISP”).
Sequence of steps for testing access to the PISP API from your APP
Step 1: Retrieve an access token
This call allows you to retrieve the token forged by the ASPSP API gateway, and is a prerequisite for each access to one of the payment initiation API methods.
A description of the functionality and fields of the request is given in the “Overview” > “Retrieve your token” section.
In order to query the correct backend in the customer journey, the TPP must first ask the customer for his or her account-holding institution.
For access to the sandbox assembly, the entry point depends on the establishment code: www.<cdetab>.sandbox.api.89c3.com
The only banking institutions that can be used in sandbox assembly for this API are the following (institution code <cdetab> used in URLs):
| Establishment code | Name of establishment | Short name |
| 13807 | B.P Grand Ouest | BPGO |
| 17515 | Caisse d’Epargne Ile De France | CEIDF |
Request :
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/oauth/token
In the headers :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
In the settings :
client_id : PSDFR-ACPR-12345
grant_type : client_credentials
scope: pisp
Notes on field feeding :
<cdetab> => establishment code of the two banks available in this environment, i.e. :
13807 (Banque Populaire Grand Ouest) ;
17515 (Caisse d’Epargne Ile de France).
client_id :
If the TPP was registered using the “GoLive” process via our 89C3 API portal.
=> approval number issued by your competent authority (PSDXX-YYYYYYY-ZZZZZZZZ)
Or if the TPP was registered using the registerclient_id API returned in the POST /register response.
=> client_id returned in response to POST /register
grant_type => non-modifiable = “client_credentials
Response:
{
“access_token“: “firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz“,
“token_type“: “Bearer”,
“expires_in“: “3600”,
“scope” : “pisp
}
Notes on field feeding :
access_token => tokenCredential to be transmitted in the authorization header of payment initiation API requests after Bearer XX.
expires_in => token validity time in seconds.
Step 2: Initiate a payment
This call allows you to initiate a payment by asking the connected PSU to consent to the payment.
The description of the functionality and fields of the request is described in the “Initiate a payment” use case.
Reminder: the authentication method supported by the bank is the reinforced REDIRECT mode => the sequences of identification and strong authentication screens described below correspond to this authentication mode.
Request :
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/v1.6.2/payment-requests
Authorization : Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Headers :
Content-Type: application/json
Signature : keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<print-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”: “2022-09-05T09:25:22.527+02:00”,
“numberOfTransactions”: 1,
“requestedExecutionDate”: “2022-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&challenge_code_method=S256&challenge_code=ABCD
}
}
Notes on field feeding :
Authorization : Bearer => access_token retrieved for the tokenCredential
The following data must be unique, otherwise the request will be rejected as a duplicate (replay is not authorised):
– paymentInformationId ;
– instructionId ;
– endToEndId ;
– x-request-id.
debtor/privateId/identification => remote bank access identifier for the PSU: when this is filled in and debtorAccount is filled in, the PSU identification screen is not called up.
debtorAccount => IBAN of the PSU: when this is entered, the only account that can be selected for the PSU is the one corresponding to this IBAN, provided that the account is eligible for PISP transfers.
The functionalities implemented may differ between the Banques Populaires and the Caisses d’Epargne (see “Initiating a payment” use case).
Response:
{
“appliedAuthenticationApproach” : “REDIRECT”,
“_links : {
“consentApproval” : {
“href” : “https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v2/identificationPisp?paymentRequestRessourceId=00000000a22-156688979900016807956016&nonce=qJammuGI0OGCwznaZ0YO”,
“templated : true
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 201 OK
Notes on field feeding :
paymentRequestRessourceId => identifier to pass to the GET /payment-requests request to retrieve the status of the payment initiation
appliedAuthenticationApproach” = “REDIRECT” => only authorised value
href => URL of the page redirecting to the school’s identification and authentication screens
nonce => anti-technical replay
currency => retrieved from the body passed as input
successfulReportUrl => retrieved from the body passed as input
unsuccessfulReportUrl => retrieved from the body passed as input
iban => retrieved from the body passed as input
creditorName => retrieved from the body passed as input
X-Request-ID: transmitted as input
Step 3: redirect to the ASPSP screens so that the PSU can validate the operation
Nominal kinematics of identification and strong authentication screen sequences
Sequence of identification and strong authentication screens :
From the URI returned in “consentApproval“, it is possible to play the sequence of screens.
1) The PSU is redirected to an identification screen provided by their bank, where they enter their remote banking identifier.
Please note: this screen can only be called up once.
=> the nonce transmitted in the URL giving access to this screen can only be used once (it is then burnt out by the anti-replay)
=> if the TPP or PSU application does not complete the entire process at once, a new payment initiation request (paymentRequest) will be required.
Enter the PSU’s remote banking identifier (see “How do I test the API?” section). > “Testing our personas” for the institution’s datasets), for example for the “Marc” persona of Banques Populaires :
Note: The “Remember me” button is not operational. Activating it serves no purpose.
For Caisses d’Epargne, if the PSU is a professional or a company, they will need to enter their user number in addition to their remote banking identifier.
2) The PSU is redirected to an initial strong authentication screen proposed by their bank to validate their identity.
The SMS code for authentication must be entered (see “How do I test the API? > “Testing our personas” for the institution’s datasets), for example for the “Marc” persona of Banques Populaires:
In live production: The kinematics of this stage depend on the strong authentication method made available to the PSU by the banking institution (SMS OTP, secur’pass, etc.).
It also depends on the PSU equipment running the PISP application used by the PSU (PC or mobile/smartphone/tablet).
Note: in a sandbox environment, the SMS code to be entered is always “12345678”.
3) The PSU is redirected to a screen for selecting the account to be debited proposed by their bank.
Example of output for the persona “Marc” from Banques Populaires, who has 4 accounts (see “How do I test the API?” > “Testing our personas” for the institution’s datasets). > “Testing our personas” for the bank’s datasets):
NB: If the PISP provides the IBAN of the PSU to be debited in its request (“debtorAccount” field), only the corresponding account will be selectable and proposed to the PSU: example below for the persona Tech’n Co des Banques Populaires.
NB: If the PSU does not have an account, the payment initiation request will not succeed and the PSU will be redirected to your APP. Example for the persona “Thomas” from Banques Populaires.
4) The PSU selects and validates the account to be debited.
5) The PSU is redirected to a second strong authentication screen proposed by their establishment to validate their payment.
Screens identical to the strong authentication screen in step (2) for validating the PSU’s identity, except for the password entry screen which is not shown.
Exemptions are possible for the AF step to validate payment => this option is not available.
The PISP can set an indicator to indicate that it considers the payment request to be a case of exemption from strong authentication. The final decision as to whether or not to apply a strong authentication exemption remains at the discretion of the PISP.
The cases in which the PSU’s strong authentication requirement may be waived if the general authentication requirements are met are described in Article 2 of the PSD2 RTS.
6) The PSU is redirected to the PISP APP.
When requesting initiation, the PISP provides one or two callback URLs:
The first (successfulReportUrl) will be called by the bank if the initiation request is processed and if the PSU has given its consent to the payment. A code parameter is added to the successfulReportUrl.
Example: https://<yourSuccessfulReportUrl>?code=GbmTn1ZZ76bibgvCRLxD4lNp8wMzkd
This information is important because it is needed to obtain the token for access to the o-confirmation method.
The second URL (unsuccessfulReportUrl) will be used by the bank if consent is refused or if the payment initiation validation process is interrupted at any stage (e.g. timeout on the identification screen, on the screen for selecting the account to be debited or on the strong authentication screens). This second URL is optional: the first call back URL (successfulReportUrl) will be used if the second is not filled in, but without adding a “code” parameter.
Alternative step 3: Redirection to the screens so that the PSU can validate the payment in the event of a smooth run
Nominal kinematics of identification and strong authentication screen sequences
By default, the PSU is asked to authenticate itself twice in order to trigger a payment request. It is possible to trigger two fluid runs when the request contains more precise information about the debtor account:
- Bis Fluid Path: the debtorAccount is entered in the payment initiation request
- Fluid path: the debtorAccount and privateId (*) are entered in the payment initiation request.
| Fluid Bis route | Fluid course |
 |
 |
NB (*) For the Caisses d’Epargne, Banque BCP, Crédit Coopératif and BTP Banque and for the PRO and ENT customer segments: this is the subscriber number separated from the user number by a hyphen “-“.
Triggering the Bis fluid path redirects the PSU to the identifier entry screen, which is the same as in the conventional path. The sequence that follows is the same regardless of the type of fluid path.
1 ) The PSU is redirected to a screen summarising the operation, and can validate or cancel it.
Example of output for the persona “Marc” from Banques Populaires, who has 4 accounts including account number 30019654051, (see the “How do I test the API? > “Test our personas” for the bank’s datasets):
2) The PSU is redirected to an initial strong authentication screen proposed by their bank to validate their identity.
The SMS code for authentication must be entered (see “How do I test the API? > “Test our personas” for the institution’s datasets), example for the persona “Marc” from Banques Populaires:
The kinematics of this stage depend on the strong authentication method made available to the PSU by the banking institution (password + SMS OTP, secur’pass, etc.).
It also depends on the PSU equipment running the PISP application used by the PSU (PC or mobile/smartphone/tablet).
Note: in a sandbox environment, the SMS code to be entered is always “12345678”.
3 ) The PSU is then redirected to the PISP’s APP, with the “code” parameter being supplied.
Step 4: Recover the status of a payment initiation
This GET /payment-requests/{paymentRequestResourceId} call enables you to retrieve all the data from the payment initiation, enriched with the resourceId and the status of the initiation and the payment it contains. The description of the functionality and the fields of the request are described in the “Recover the status of a payment initiation” use case. The data is accessible for 35 days.
For access to the sandbox assembly, the entry point is identical to the previous requests:
Request :
Headers :
Authorization : Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Content-Type: application/json
Signature : keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<print-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 field feeding :
Authorization : Bearer => access_token retrieved for the 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 payment.
Response:
{
“paymentRequest”: {
“resourceId”: “0000000a22-156688979900016807956016”,
“paymentInformationId”: “azertyui 1630919339”,
“creationDateTime”: “2022-09-05T09:25:22.527+02:00”,
“numberOfTransactions”: 1,
“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
]
}
},
“debtorAccount”: {
“iban”: “FR7613807000243021933556300”
},
“debtorAgent”: {
“bicFi”: “CCBPFRPP512”,
“clearingSystemMemberId: {
“clearingSystemId”: “clearingSystemId”,
“memberId”: “memberId”
},
“name”: “Cpy Name”,
“postalAddress”: {
“country”: “FR”,
“addressLine”: [
“512 rue De Gaulle,
“85000 LRSY
]
}
},
“beneficiary”: {
“isTrusted”: false,
“creditorAgent”: {
“bicFi”: “CCBPFRPP512”,
“clearingSystemMemberId: {
“clearingSystemId”: “clearingSystemId”,
“memberId”: “memberId!”
},
“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”
}
},
“chargeBearer”: “SLEV”,
“paymentInformationStatus”: “ACCP”,
“requestedExecutionDate”: “2022-09-06T14:10:10.109+01:00”,
“creditTransferTransaction”: [
{
“paymentId”: {
“resourceId”: “0000006537-163091934100113807153727”,
“instructionId”: “instructionId 1630919339”,
“endToEndId”: “endToEndId 1630919339”
},
“requestedExecutionDate”: “2022-09-06T15:10:10.109+02:00”,
“instructedAmount: {
“currency”: “EUR”,
“amount”: “2.41
},
“purpose”: “COMC”,
“regulatoryReportingCodes”: [],
“remittanceInformation”: {
“unstructured”: [
“remittanceInformation01
]
}
}
],
“supplementaryData”: {
“acceptedAuthenticationApproach”: [
“REDIRECT
],
“appliedAuthenticationApproach”: “REDIRECT”,
“scaHint”: “scaExemption”,
“successfulReportUrl“: “https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK-12345&code_challenge_method=S256&code_challenge=ABCD”
}
},
“_links: {
“request”: {
“href”: “/stet/psd2/v1.6.2/payment-requests/00000000a22-156688979900016807956016”,
“templated: false
},
“confirmation”: {
“href”: “/stet/psd2/v1.6.2/payment-requests/00000000a22-156688979900016807956016/confirmation”,
“templated: false
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Notes on field feeding :
resourceId => uses the paymentRequestResourceId
paymentInformationStatus => shows the status of the payment initiation
transactionStatus => shows the status of the resourceId transaction
X-Request-ID: transmitted as input
Step 5: Confirm a payment initiation (only in production, NOT in sandbox)
This POST call /payment-requests/{paymentRequestResourceId}/o-confirmation allows you to confirm a payment initiation. The description of the functionality and the fields of the request are described in the “Confirm a payment initiation” use case.
The POST method /payment-requests/{paymentRequestResourceId}/confirmation is not implemented.
Before the o-confirmation service can be used, a specific access token must be obtained via the following request:
Request :
POST https://www.13807.live.api.89C3.com/stet/psd2/oauth/token
In the Headers :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
In the body :
grant_type : authorization_code
client_id : PSDFR-ACPR-12345
code: the code retrieved as a parameter from the successfulReportUrl call at the end of step 3
code_verifier: based on your PKCE elements
redirect_uri: https://myAPP.fr/Home/OAuth2Callback
Notes on field feeding :
<cdetab> => establishment code of the two banks available in this environment, i.e. :
13807 (Banque Populaire Grand Ouest) ;
17515 (Caisse d’Epargne Ile de France).
client_id :
If the TPP was registered using the “GoLive” process via our 89C3 API portal:
=> this is the approval number given by your competent authority (PSDXX-YYYYYYY-ZZZZZZZZ)
OR
if the TPP was registered using the register API, client_id returned in the response to the POST /register :
=> this is the client_id returned in the response to the POST /register
redirect_uri: pre-declared redirect URL in your consuming application AND to be communicated to the ASPSP:
- during the GO Assembly stage (or GO Live in production) if the TPP has been registered using the current procedure;
- via the API Register if the TPP has registered using the automated procedure.
grant_type => non-modifiable = “authorization_code
Response:
{
“access_token“: “secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs“,
“token_type“: “Bearer”,
“expires_in“: “3600”,
“refresh_token“: “1ji8KA9RJ5eXeJV1xKSDj1WDp8wwg3pRgDO2j0WhtbMsWz”,
“scope“: “pisp”,
“state“: “OK-12345”
}
Notes on field feeding :
access_token => second token to be transmitted in the header of the next method near Bearer XX.
expires_in => token validity time in seconds.
refresh_token => to be memorised: is used to obtain a new access token if the validity period of the first token has expired (lasting a few minutes). The token is refreshed using grant-type= refresh_token.
state => The ASPSP restores the “state” value that was present in the initial payment initiation request (value set by the TPP).
Once the access token has been obtained, you can call up the payment initiation confirmation request below (“Authorization” field).
Request:
Headers :
Authorization : Bearer secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs
Content-Type: application/json
Signature : keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<print-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 :
{
}
Notes on field feeding :
Authorization : Bearer => second access_token retrieved for the tokenCredential
{paymentRequestResourceId} : this is the identifier transmitted by the payment service at the time of initiation and used for the GET.
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://extensions.bpce.fr/OAuth2Callback.aspx&state=OK- 12345&challenge_code_method=S256&challenge_code=T3LPv9JWu_HtyEQOkDCo4YYRmZJXTjJ0Ng9jfq_UBBg
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Notes on field feeding :
paymentRequestResourceId => identifier to pass to the POST/payment-requests request to confirm payment initiation
appliedAuthenticationApproach” = “REDIRECT” => only authorised value
href => URL of the page redirecting to the school’s identification and authentication screens
nonce => anti-technical replay
Step 6: Cancel a Payment Initiation
This call allows you to cancel a payment initiation by asking the connected PSU to give its consent to the cancellation. The description of the functionality and the fields of the request are described in the “Cancel a payment initiation” use case.
Reminder: the authentication method supported by the bank is the REDIRECTsimple mode => the kinematics of the identification and strong authentication screen sequence described below correspond to this authentication mode.
For access to the sandbox assembly, the entry point is identical: www.<cdetab>.sandbox.api.89c3.com
Request :
Headers :
Authorization : Bearer secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs
Content-Type: application/json
Signature : keyId=\”https://<www.myUrlPath.to>/myQsealCertificate_<print-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 :
{
“resourceId”: “0000000a22-156688979900016807956016”,
“paymentInformationId: “MyPmtInfld123”,
“creationDateTime”: “2022-09-05T09:25:22.527+02:00”,
“numberOfTransactions”: 1,
“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
]
}
},
“debtorAccount”: {
“iban”: “FR7613807000243021933556300”
},
“debtorAgent”: {
“bicFi”: “CCBPFRPP512”,
“clearingSystemMemberId: {
“clearingSystemId”: “clearingSystemId”,
“memberId”: “memberId”
},
“name”: “Cpy Name”,
“postalAddress”: {
“country”: “FR”,
“addressLine”: [
“512 rue De Gaulle,
“85000 LRSY
]
}
},
“beneficiary”: {
“isTrusted”: false,
“creditorAgent”: {
“bicFi”: “CCBPFRPP512”,
“clearingSystemMemberId: {
“clearingSystemId”: “clearingSystemId”,
“memberId”: “memberId!”
},
“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”
}
},
“chargeBearer”: “SLEV”,
“paymentInformationStatus”: “ACCP”,
“creditTransferTransaction”: [
{
“paymentId”: {
“resourceId”: “0000000a22-156688979900016807956016”,
“instructionId”: “instructionId 1630919339”,
“endToEndId”: “endToEndId 1630919339”
},
“requestedExecutionDate”: “2022-09-06T14:10:10.109+01:00”,
“instructedAmount: {
“currency”: “EUR”,
“amount”: “2.41
},
“purpose”: “COMC”,
“regulatoryReportingCodes”: [],
“remittanceInformation”: {
“unstructured”: [
“remittanceInformation01
]
},
“transactionStatus”: “RJCT”,
“statusReasonInformation”: “DS02”
}
],
“supplementaryData”: {
“acceptedAuthenticationApproach”: [
“REDIRECT”,
“DECOUPLED
],
“appliedAuthenticationApproach”: “REDIRECT”,
“scaHint”: “scaExemption”,
“successfulReportUrl“: “https://extensions.bpce.fr/OAuth2Callback.aspx&state=OK-12345&code_challenge_method=S256&code_challenge=T3LPv9JWu_HtyEQOkDCo4YYRmZJXTjJ0Ng9jfq_UBBg”
}
}
Notes on field feeding :
Authorization : Bearer => second access_token retrieved
{paymentRequestResourceId} : this is the identifier transmitted by the payment service at the time of initiation and used for the GET.
The data in the body must be identical to that retrieved at the time of the GET, except for the following at the level of the transaction to be cancelled:
– the transactionStatus of the creditTransferTransaction object, which must be set to “RJCT”.
– set the statusReasonInformation of the creditTransferTransaction object to “DS02”.
– the _links part must be deleted
– the object envelope of the “paymentRequest” parent: {must be deleted, along with the associated closing brace at the end of the flow.
Response:
{
“appliedAuthenticationApproach”: “REDIRECT”,
“_links”: {
“consentApproval”: {
“href”: “https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v1.6.2/cancellation?paymentRequestRessourceId=0000000a22-156688979900016807956016&nonce=Ij4VifKlm4QICq12345”,
“templated”: true
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Notes on field feeding :
paymentRequestResourceId => identifier to pass to the GET /payment-requests request to retrieve the status of the payment initiation
appliedAuthenticationApproach” = “REDIRECT” => only authorised value
href => URL of the page redirecting to the school’s identification and authentication screens
nonce => anti-technical replay
currency => retrieved from the body passed as input
successfulReportUrl => retrieved from the body passed as input
unsuccessfulReportUrl => retrieved from the body passed as input
creditorAccount => retrieved from the body passed as input
creditorName => retrieved from the body passed as input
amount => retrieved from the input body
successfulReportUrl => retrieved from the body passed as input
debtorAccount => retrieved from the body passed as input
debtorName => retrieved from the body passed as input
privateId => retrieved from the body passed as input
requestedExecutionDate=> retrieved from the body passed as input
method => UFVU is equal to PUT in base64 + URL
X-Request-ID: transmitted as input
Step 7: The customer is redirected to the screens to confirm the cancellation of a payment initiation.
Nominal kinematics of identification and strong authentication screen sequences
Sequence of identification and strong authentication screens :
The URI returned in consentApproval can be used to sequence the screens.
1) The PSU is redirected to an identification screen provided by their bank, where they enter their remote banking identifier.
Please note: this screen can only be called up once.
=> the nonce transmitted in the URL giving access to this screen can only be used once (it is then burnt out by the anti-replay)
=> a new DSP2 transfer cancellation request (via PUT PaymentRequest ) is required to recover a new nonce token if necessary.
The PSU’s remote banking identifier must be entered (see the “How do I test the API?” section). > “Test our personas” for the institution’s datasets), example for the persona “Marc” from Banques Populaires :
For Caisses d’Epargne, if the PSU is a professional or a company, they will need to enter their user number in addition to their remote banking identifier:
2) The PSU is redirected to a strong authentication screen offered by their bank to validate their identity.
The SMS code for authentication must be entered (see the section “How do I test the API?” > “Test our personas” for the institution’s datasets), example for the persona “Marc” from Banques Populaires:
The kinematics of this stage depend on the strong authentication method made available to the PSU by the banking institution (SMS OTP, secur’pass, etc.).
It also depends on the PSU equipment running the PISP APP used by the PSU (PC or mobile/smartphone/tablet).
Note: in a sandbox environment, the SMS code is systematically “12345678”.
3) The PSU is redirected to a summary screen of the transaction being cancelled, as proposed by their bank.
Example of a refund for the persona “Marc” from Banques Populaires who wants to cancel his transaction of 2.12 euros issued from his Personal Account. He can cancel or validate his cancellation transaction.
4) The PSU validates the cancellation of the transfer.
5) The PSU is redirected to a transaction confirmation screen provided by their bank.
NB: if the PSU does not confirm the payment cancellation (or if there is a timeout on the transaction summary page, for example), the PSU is redirected to the next page,
6) The PSU is redirected to the TPP PISP application.
When requesting cancellation, the PISP provides one or two callback URLs:
The first (successfulReportUrl) will be called by the bank if the cancellation request is processed and if the PSU has given its consent for the transaction to be cancelled.
The second URL (unsuccessfulReportUrl) will be used by the bank if consent is refused or if the payment cancellation validation process is interrupted at any stage (e.g. timeout on the identification screen, on the transaction summary screen or on the strong authentication screens). This second URL is optional: the first call back URL (successfulReportUrl) will be used if the second is not filled in.
NB: confirmation of the cancellation of a payment request will not be implemented: confirmation will be implicitly carried by the PSU’s acceptance of the cancellation request itself.
Version history
Version of the STET standard used for the API
This REST API complies with the French interbank specification STET (https://www.stet.eu/en/psd2/), version v.1.6.2.0, in order to meet the regulatory requirements of PSD2. It takes into account the functional limitations specific to Banque de Savoie described in the “Limitations” section.
As a reminder:
- the texts of Payment Directive number 2 (PSD2, EU reference 2015/2366 of 25/11/2015) came into force on 13 January 2018: http://eur-lex.europa.eu/legal-content/FR/TXT/?uri=CELEX:32015L2366
- They have been supplemented by regulatory technical standards (RTS, EU Delegated Regulation 2018/389) relating to strong customer authentication and common secure open communication standards, which will come into force on 14 September 2019. These standards are the 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, Order 2017-1252 of 9 August 2017 transposes the PSD2 Directive into the legislative part of the Monetary and Financial Code. The Order is supplemented at regulatory level by Decrees 2017-1313 and 2017-1314 of 31 August 2017 and the five Orders of 31 August 2017.
You can also consult the virtual assistant about STET specifications.
Users can also consult the virtual assistant by clicking on the pictogram on the portal home page.
Description of the support
In accordance with article 30 (5) of the RTS, support for third-party PSP providers is available. This user support can be accessed via the form on this 89C3 API portal, or via https://www.api.89c3.com/fr/nous-contacter. Responses are provided during normal working hours.
To query an API, the API version includes the version number in the URI called, for example: /stet/psd2/v1.6.2/payment-requests.
The “Roadmap” use case gives the correspondence table between the API version and the version of the specification used, for example API v1 corresponds to version V1.4.0.47 of the STET specifications, v1.4.2 corresponds to version v1.4.2.17 of the STET specifications and v1.6.2 corresponds to version v1.4.6.0 of the STET specifications.
The principle of the support period is illustrated below, taking into account article 30 (4) of the RTS:
API versioning
| Our API versions | STET standard version |
| v1 | v1.4.0.47 |
| v1.4.2 | v1.4.2.17 |
| v1.6.2 | v1.6.2.0 |
You can consult the virtual assistant about the texts of the STET standard.
Major changes since the first version delivered
| Use case / Method(s) | Effective date | Description of the evolution |
| POST /payment-requests GET /payment-requests/{paymentRequestResourceId} | 17 May 2019 | Portal documentation :
· Added clarification on the mandatory or optional nature of query parameters and fields. |
| All | 31 July 2019 | Portal documentation :
· Description of the sandbox assembly on target at the end of August 2019; o added details (limitations, examples, availability date, etc.) for all API use cases. |
| Roadmap | 18 September 2019 | Portal documentation :
· Modified roadmap for sandbox and live. |
| Eligibility | 1st October 2019 | Portal documentation :
· Added details of the QWAC and QSEALC certificates required for a goLive application. |
| Initiating a payment | 19 November 2019 | Portal documentation:
· Added clarification: “For Banques de Savoie, the requestedExecutionDate cannot be a weekend or a target 2 day for SCT”. |
| How to use fallback | 21 November 2019 | Portal documentation :
· Adding an example |
| Recover the status of a payment initiation | 9 December 2019 | Portal documentation :
· Addition of a table showing the possible values for the status of the payment initiation and the associated payment transaction. |
| Testing our personas | 23 December 2019 | Portal documentation :
· The following clarification has been added to the use case: “THESE IDENTIFIERS AND TEST DATA CANNOT BE USED IN LIVE PRODUCTION. o Changes to persona remote banking identifiers => these new identifiers have been active since 8 January 2020 (the old identifiers have been deactivated) |
| Initiating a payment | 24 December 2019 | Enable the IBAN transmitted in the debtorAccount => PSU IBAN field to be taken into account: when it is entered, the only account that can be selected for the PSU is the one corresponding to this IBAN. |
| Version history / roadmap | 30 December 2019 | Portal documentation :
· Added details on API versioning and decommissioning management. |
| Limitations / Version history / roadmap | 25 February 2020 | Activation of the API for BPs other than BPGO.
Modification of API versioning. |
| Cancelling a payment initiation / sandbox / limitations | 10 September 2020 | Activate the method for cancelling a payment initiation. |
| POST /payment-requests | 2 December 2020 | Portal documentation :
· Addition of details on the triggering of the two fluid paths when a PISP payment is initiated |
| Initiate a payment / Recover the status of a payment initiation / Sandbox / Roadmap | 22 December 2020 | Since 7 December :
· Activation of the PISP fluid path ; · Rejection of transfers with categoryPurpose = “CASH” when the AF is not made with Sécur’Pass and the beneficiary is not known. o If the PSU does not take any consent action (validation or refusal) within 30 minutes of the RJCT initiation request (NOAS reason). |
| All | 4 January 2021 | Portal documentation :
· DSP2 STET API documentation updated from version v1 to v1.4.2 |
| All | 19 July 2021 | Portal documentation :
· Activation of payment initiations for permanent SCTs. NB: cancellations of payment initiations for permanent SCTs should only be available in September 2021. · The chargeBearer field is optional for euro transfers. o Clarification on the management of clientId following the registration of the TPP via the “GoLive” process of our 89C3 API portal via the API register. |
| Initiating a payment | 22 July 2021 | Portal documentation :
· Added clarification that the size of the beneficiary.creditor.name data item is limited to 35 characters. |
| Sandbox / Try-IT | 23 September 2021 | Portal documentation :
· Added details of the /o-confirmation method, which is not available in sandboxes. · Correction of examples for v1.4.2. o Removal of the transfer confirmation screen on the ASPSP side (equivalent screen proposed by the TPP after the /o-confirmation) |
| Initiating a payment | 27 September 2021 | Portal documentation :
· Addition of details on the format of IBAN and debtor.privateId.identification data |
| All | 22 March 2022 | Portal documentation :
· Activation of payment initiations for SEPA Instant Payments; · Correction of the double “s” in “ressourceId” and “paymentRequestResourceId”: · Addition of details on the signature pad for Banque Palatine; · Provision of PUT /paymentRequests and POST /paymentRequests/o-confirmation in sandbox; · Added details on the PUT /paymentRequests for the valuation of transactionStatus (= “CANC”), paymentInformationStatus and statusReasonInformation data; o Activate cancellations for standing orders. |
| Initiating a payment / limitations | 20 April 2022 | Portal documentation :
· Added details for SEPA Instant Payments for B2B: eligible accounts and countries are defined in the B2B IP flow contract. o The following clarification has been added: a transfer initiated via the Payment Initiation API cannot be cancelled by the PSU via its direct access. |
| All | 26 September 2022 | Portal documentation :
· The DSP2 STET API documentation has been updated from version v1.4.2 to version v1.6.2 => v1.6.2 will be activated in the sandbox on 20 October 2022 and live in January 2023. The “o-confirmation” method is no longer supported => renamed to “confirmation”. · Addition of rules for a multiple transfer, which will be available in February 2023. · Addition of categoryPurpose = “SALA”: rules aligned with those of categoryPurpose = “CASH”. o The following rule: “The requestedExecutionDate cannot be a weekend or a target 2 day for SCTs. Otherwise, an error is generated and the payment is rejected. This limitation does not apply to immediate SCTs only if requestedExecutionDate is on the same day as the request; in this case, the payment will be transformed into a deferred SCT scheduled for the next business day” becomes “The requestedExecutionDate can be a weekend or a target 2 day for SCTs: if requestedExecutionDate is on the same day as the request; in this case, the payment will be transformed into a deferred SCT scheduled for the next business day. |
| Confirmation / Limitations | 21 March 2023 | Portal documentation :
· Restitution of details of 500 error messages (Internal Server Error) added in return for confirmation of a payment. · BCP bank customers will have access to the payment initiation API in mid-June 2023, following the migration of BCP branches to BPALC bank with their Luxembourg IBAN: addition of the James persona for sandbox testing. |
Roadmap
API version decommissioning policy
The decommissioning policy (= stopping a version of an API on production and sandbox environments) is a function of the API life cycle, and a tiling phase is planned between two major API versions as shown in the diagram below:
Communication of the decommissioning of version N will take place on the deployment date of version N+1. The preferred communication channel is the 89C3 API portal in the “Roadmap” section of the API affected. An e-mail communication to the correspondents of the service providers registered on the 89C3 API portal may be added to this system.
Schedule of future functional changes to the API
The Account Information API is subject to continuous improvement and development throughout the year*.
(*) NB: article 30 (4) of the RTS specifies that significant changes to the API may be made without delay. We apply this clause in the following cases:
- blocking problem having a widespread impact on at least one of the major customer segments (individuals, professionals, businesses),
- safety issues,
- changes requested by the competent national authorities to meet the regulatory trajectory.
See below for our projected roadmap.
| API version | STET standard version | Features | Sandbox
Deployment date 89C3 API Dev Portal & Sandbox |
Live
Deployment date 89C3 Live API Gate way |
Decommissioning date |
| v1 | v1.4.0.47 | · Initiate a single transfer in euros (SCT immediate / SCT deferred)
· Retrieve the status of a payment initiation for a single credit transfer (SCT immediate / SCT deferred) |
14 March 2019 (1st version)
7 October 2019 (REDIRECT mode) |
7 October 2019 | April 2023
(to be confirmed) |
| v1 | v1.4.0.47 | · Initiate a single transfer in euros (SCT immediate / SCT deferred)
· Retrieve the status of a payment initiation for a single credit transfer (SCT immediate / SCT deferred) · Cancel a payment initiation for a single credit transfer (deferred SCT) |
24 August 2020 | 24 August 2020 | April 2023
(to be confirmed) |
| v1 | v1.4.0.47 | · Initiate a single transfer in euros (SCT immediate / SCT deferred)
· Retrieve the status of a payment initiation for a single credit transfer (SCT immediate / SCT delayed) · Cancel a payment initiation for a single credit transfer (deferred SCT) · Smooth customer process for initiating a payment (1 single AF if the customer ID and the accounts to be debited and credited are transmitted) |
7 December 2020 | 7 December 2020 | April 2023
(to be confirmed) |
| v1.4.2 | v1.4.2.17 | · Initiate a single transfer in euros (SCT immediate / SCT deferred)
· Retrieve the status of a payment initiation for a single credit transfer (SCT immediate / SCT deferred) · Cancel a payment initiation for a single credit transfer (deferred SCT) · Smooth customer process for initiating a payment (1 single AF if the customer ID and the accounts to be debited and credited are transmitted) · Confirm a payment initiation for a single euro transfer (SCT immediate / SCT deferred) |
30 May 2021 | 30 May 2021 | |
| v1.4.2 | v1.4.2.17 | · Initiate a single transfer in euros (immediate SCT / deferred SCT / permanent SCT)
· Retrieve the status of a payment initiation for a single credit transfer (immediate SCT / deferred SCT / permanent SCT) · Cancel a payment initiation for a single credit transfer (deferred SCT) · Smooth customer process for initiating a payment (1 single AF if the customer ID and the accounts to be debited and credited are transmitted) · Confirm a payment initiation for a single euro transfer (immediate SCT / deferred SCT / permanent SCT) |
30 June 2021 | 30 June 2021 | |
| v1.4.2 | v1.4.2.17 | · Initiate a single transfer in euros (SCT immediate / SCT deferred / SCT permanent / Instant PaymentPART and B2B)
· Retrieve the status of a payment initiation for a single credit transfer (immediate SCT / deferred SCT / permanent SCT / Instant Payment PART and B2B) · Cancel a payment initiation for a single credit transfer (SCT deferred / SCT standing) · Smooth customer process for initiating a payment (1 single AF if the customer ID and the accounts to be debited and credited are transmitted) · Confirm a payment initiation for a single euro transfer (immediate SCT / deferred SCT / permanent SCT / Instant Payment PART and B2B) |
30 March 2022 | 30 March 2022 | |
| v1.6.2 | v.1.6.2.0 | · Initiate a single transfer in euros (SCT immediate / SCT deferred / SCT permanent / Instant Payment PART and B2B)
· Retrieve the status of a payment initiation for a single credit transfer (immediate SCT / deferred SCT / permanent SCT / Instant Payment PART and B2B) · Cancel a payment initiationv for a single credit transfer (SCT deferred / SCT standing) · Smooth customer process for initiating a payment (1 single AF if the customer ID and the accounts to be debited and credited are transmitted) · Confirm a payment initiation for a single euro transfer (immediate SCT / deferred SCT / permanent SCT / Instant Payment PART and B2B) |
20 October 2022 | 8 February 2023 | |
| v1.6.2 | v.1.6.2.0 | · Initiate a single transfer in euros (SCT immediate / SCT deferred / SCT permanent / Instant Payment PART and B2B)
· Retrieve the status of a payment initiation for a single credit transfer (immediate SCT / deferred SCT / permanent SCT / Instant Payment PART and B2B) · Cancel a single payment initiation for a single transfer (SCT deferred / SCT standing) · Smooth customer process for initiating a payment (1 single AF if the customer ID and the accounts to be debited and credited are transmitted) · Confirm a payment initiation for a single euro transfer (immediate SCT / deferred SCT / permanent SCT / Instant Payment PART and B2B) · Initiate a mulitiple transfer in euros (SCT immediate / SCT deferred PART and B2B) · Recover the status of a payment initiation for a multiple credit transfer in euros (SCT immediate / SCT deferred PART and B2B) · Cancel a payment initiation for a multiple transfer (SCT deferred) · Confirm a payment initiation for a multiple transfer in euros (SCT immediate / SCT deferred PART and B2B) |
22 February 2023 | 22 February 2023 |
Limitations
Functional limitations
Limitations of this DSP2 API in version 1.6.2
- Applies to Banque de Savoie
- Applies only to euro payment accounts that are active and accessible online (see text of the PSD2 Directive);
- Uses only the REDIRECTenforced authentication mode (calls the confirmation method so that the TPP can confirm the payment after Strong Authentication of the PSU has been requested and managed via the bank: the ASPSP sends an OAUTH2 authorisation code to the TPP, which must send it back to the ASPSP to confirm the payment).
NB: the TPP cannot provide the ASPSP with the customer’s personalised security data for authentication purposes, and therefore only the ASPSP’s redirection and strong authentication (SCA) screens must be used (encapsulation of these screens by the TPP is prohibited under PSD2 #97.5 and RTS #31).
- Only processes payment initiation requests in €uro
- So no initiation of foreign currency transfers
- Immediate, standing or deferred SEPA SCT single credit transfers, or SEPA Instant Payment (SCTInst).
- Immediate or deferred SEPA SCT multiple credit transfers.
- The chargeBearer field is mandatory for the POST /payment-requests method and must be SLEV for international payments (i.e. in currencies other than EUR) => international transfers in foreign currency are not available.
- The categoryPurpose field is mandatory for the POST /payment-requests method:
- CASH, SALA and DVPM are available for single transfers;
- CASH and SALA are available for multiple transfers.
- The following methods are available:
- POST /payment-requests and POST /payment-requests/{paymentRequestResourceId}/confirmation to initiate a payment for a single or multiple transfer
- GET /payment-requests/{paymentRequestResourceId} to retrieve the status of a payment initiation for a single transfer or a multiple transfer
- The PUT /payment-requests/{paymentRequestResourceId} method is only supported for cancelling a payment initiation for a single transfer (deferred or standing SCT transfer) or a multiple transfer (deferred SCT).
- The POST method /payment-requests/{paymentRequestResourceId}/o-confirmation is no longer supported in v1.6.2
- The GET /payment-requests/{paymentRequestResourceId}/transactions method is not supported.
- Remote bank identifier of the bank customer taken into account (via the debtor/privateId/identification data) to trigger a fluid PISP path (a single strong authentication) if the debtorAccount is also entered in the request.
- A transfer initiated via the Payment Initiation API cannot be cancelled by the PSU via its direct access to online banking.
- If no action is taken by the user after 30 minutes (or 04 minutes on redirection screens), this is considered to be a disconnection with no redirection back to the TPP.
Limitations linked to customer segments
- The individual (PART) is a natural person categorised as a “capable adult”.
- The “professional” (PRO) and “company” (ENT) categories cover legal entities.
Limitations on the types of accounts accessible
- The accounts accessible via the PISP API to be debited are those available on the remote bank for initiating a SEPA transfer to an external beneficiary.
- It should be noted that, in accordance with the regulations, the ASPSP may apply business processes (anti-fraud, etc.) which may lead to the rejection of the execution of a payment initiation.
Limitations linked to strong authentication methods
- Private customer (PART): equipment with password + SMS OTP and/or Sécur’pass (triggered as a priority if necessary)
- Professional customers (PRO) and companies (ENT): Certificate and/or Sécur’Pass and/or CAP reader and/or Password + SMS OTP equipment
NB: There is no strong authentication exemption (scaHint data ignored).
Access to production data
In accordance with the regulations, the Try-it and Assemble test modes only use fictitious data. This test data is described in the “How to test the API” use cases.
To access production data, you need to use our “API Register” self-enrolment API (see the dedicated product sheet).
The weekly Sunday morning slot from 2am to 6am is used if necessary for backend / gateway maintenance and may generate KO requests until all the servers concerned have been updated for the establishment concerned.
As in test mode, the institution code (see the list of banks accessible below) will enable you to address the correct customer repository via the endpoint www.10548.live.api.89c3.com or www.10548.live.api.banque-de-savoie.fraligné on the direct access domain namewww.banque-de-savoie.fr.
Once chosen, this access point must be retained for all underlying requests.
| Establishment code | Name of establishment | Short name | Available in Try-it and Assemblage | Available in Production |
| 10548 | Banque de SAVoie | BQSAV | Yes |
