Natixis – Initiation de paiement (Norme STET V1.6.2)

Présentation du processus fonctionnel de l'initiation de paiement

Description des services proposés [NORME STET V1.6.2]

Prérequis

Le TPP est accrédité par l’autorité de contrôle prudentiel et de résolution (ACPR) pour le rôle de PISP.

Vous devez ensuite procéder à la récupération de credentials (Client_Id et Secret_key) liés à votre de votre APP sur notre portail afin de poursuivre le processus.

Un jeton d’accès OAUTH2 a été délivré par l’établissement, obtenu avec les crédentials.

Le TPP et l’établissement se sont authentifiés mutuellement (échanges des certificats eIDAS QWAC).

Le TPP a présenté son jeton d’accès OAUTH2 pour consommer les servies de l’API d’initiation de paiement.

Initier un paiement

Cas d’utilisation de l’API d’initiation de paiement :

• Le PISP fait une demande de paiement pour le compte d’un commerçant : Le PSU achète des biens ou des services sur un site e-commerce.

Il existe un contrat entre le e-commerçant et le PISP. L’e-commerçant transmet les caractéristiques du paiement demandé au PISP et redirige le PSU vers le portail du PISP.

Le PISP prépare la demande de paiement et l’envoie à l’établissement teneur de compte.

L’IBAN bénéficiaire de l’e-commerçant, le montant et la date de la transaction sont indiqués dans la demande d’initiation de paiement.

• Le PISP fait une demande de virement pour le compte du titulaire du compte. Le PSU fournit au PISP les informations nécessaires au transfert.

Le PISP prépare la demande de virement et l’envoie à l’établissement qui détient le compte du PSU.

La méthode d’authentification supportée par l’établissement et le mode REDIRECT.

Le PISP fournit lors de sa demande d’initiation un ou deux URL callback. La première sera appelée par l’établissement dans le cas où la demande d’initiation est traitée et si le PSU a donné son consentement pour le paiement.

La seconde URL call back sera utilisée par l’établissement en cas de refus du consentement . Cette deuxième URL est facultative.

Obtenir les données de l’initiation de paiement

Cet appel permet au PISP de récupérer l’ensemble des données de l’initiation de paiement enrichies des identifiants ressources et des statuts de l’initiation et du paiement qu’elle contient .

Les données sont accessibles pendant 35 jours.

Modifier une initiation de paiement

Cet appel permet au PISP d’annuler une initiation de paiement tant que le paiement n’est pas considéré comme exécuté par la banque.

Confirmer une initiation de paiement

Service non disponible en mode redirect (recueil du consentement).

Publications réglementaires

/stet/psd2/v1.6.2/payment-requests/{paymentRequestResourceId}/confirmation

paymentRequestConfirmation

Résumé

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

Description

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

Scopes

• cbpii
• pisp

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.6.2/payment-requests/{paymentRequestResourceId}

paymentRequests

Résumé

Cancellation of a Payment/Transfer Request (PISP)

Description

Description
The PISP sent a Payment/Transfer Request through a POST command.
The ASPSP registered the Payment/Transfer Request, updated if necessary the relevant identifiers in order to avoid duplicates and returned the location of the updated Request.
The PISP got the Payment/Transfer Request that was updated with the resource identifiers, and eventually the status of the Payment/Transfer Request and the status of the subsequent credit transfer.
The PISP requests for the payment cancellation (global cancellation) or for some payment instructions cancellation (partial cancellation)
No other modification of the Payment/Transfer Request is allowed.
### Prerequisites
– The TPP was registered by the Registration Authority for the PISP role
– The TPP was provided with an OAUTH2 « Client Credential » access token by the ASPSP (cf. § 3.4.2).
– The TPP previously posted a Payment/Transfer Request which was saved by the ASPSP (cf. § 4.5.3) – The ASPSP answered with a location link to the saved Payment/Transfer Request (cf. § 4.5.4) – The PISP retrieved the saved Payment/Transfer Request (cf. § 4.5.4)
– The TPP and the ASPSP successfully processed a mutual check and authentication
– The TPP presented its « OAUTH2 Client Credential » access token.
– The TPP presented the payment/transfer request.
– The PSU was successfully authenticated. ^{Business flow}
# Payment/Transfer request cancellation circumstances
The cancellation of a Payment/Transfer request might be triggered by the PISP upon request of the PSU.
It can also be triggered by the PISP itself in case of error or fraud detection.
Since the consequence of the cancellation will be a rejection of the Payment/Transfer request globally or limited to some of its instructions, the modification of the payment request will focus on setting the relevant status to the value « CANC ».
This « CANC » status must however be explained through a reason code that can be set with the following values: | Reason | description |
| —— | ———– |
| DS02 | The PSU himsef/herself ordered the cancellation. |
| DUPL | The PISP requested the cancellation for a duplication of a previous Payment/Transfer request |
| FRAD | The PISP requested the cancellation for fraudulent origin of the Payment/Transfer request |
| TECH | The PISP requested the cancellation for a technical issue on its side | #### Payment/Transfer request cancellation level
– Case of a payment with multiple instructions or a standing order, the PISP asks to cancel the whole Payment/Transfer or Standing Order Request including all non-executed payment instructions by setting the [paymentInformationStatus] and the relevant [statusReasonInformation] at payment level.
– Case of a payment with multiple instructions, the PISP asks to cancel one or several payment instructions by setting the [transactionStatus] and the relevant [statusReasonInformation] at each relevant instruction level. The cancellation request might need a PSU authentication before committing, especially when the request is PSU-driven. In other cases, the ASPSP may consider that a PSU authentication is irrelevant.
In order to meet all possibilities, the cancellation request must nevertheless include:
– The specification of the authentication approaches that are supported by the PISP (any combination of « REDIRECT » and « DECOUPLED » values).
– In case of possible REDIRECT or DECOUPLED authentication approach, one or two call-back URLs to be used by the ASPSP at the finalisation of the authentication and consent process : – The first call-back URL will be called by the ASPSP if the Transfer Request is processed without any error or rejection by the PSU – The second call-back URL is to be used by the ASPSP in case of processing error or rejection by the PSU. Since this second URL is optional, the PISP might not provide it. In this case, the ASPSP will use the same URL for any processing result. – Both call-back URLS must be used in a TLS-secured request.
– In case of possible « DECOUPLED » approach, a PSU identifier that can be processed by the ASPSP for PSU recognition. – The ASPSP saves the updated Payment/Transfer Request and answers to the PISP. The answer embeds – The specification of the chosen authentication approach taking into account both the PISP and the PSU capabilities. – In case of chosen REDIRECT authentication approach, the URL to be used by the PISP for redirecting the PSU in order to perform an authentication. Case of the PSU neither gives nor denies his/her consent, the Cancellation Request shall expire and is then rejected to the PISP. The expiration delay is specified by each ASPSP.
If any modification of the payment request other than cancellation is applied by the PISP, the ASPSP must reject the request with HTTP403 without modifying the payment request resource. There is no need for the PISP to post a confirmation of the cancellation request.

Scopes

• pisp
• cbpii

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.6.2/payment-requests/{paymentRequestResourceId}/transactions

paymentRequestTransactions

Résumé

Retrieval of the Credit Transfert Transactions that were processed for a given payment request (PISP)

Description

^{Description
The PISP gets the execution history of a payment request.
This entry-point is an alternative to the retrieval of the history through the retrieval of the payment request.
So, each ASPSP may choose or not to implement this entry-point.} Prerequisites
– The TPP was registered by the Registration Authority for the PISP role
– The TPP has previously posted a Standing Order Request which was saved by the ASPSP (cf. § 4.5.3) – The ASPSP has answered with a location link to the saved Payment Request (cf. § 4.5.4) – The TPP has retrieved the saved request in order to get the relevant resource Ids (cf. § 4.6).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP was provided with an OAUTH2 « Client Credential » access token by the ASPSP (cf. § 3.4.2).
– The TPP presented its « OAUTH2 Client Credential » access token. ^{Business flow
The PISP post the history request.
The ASPSP answers with the list of relevant transactions.}

Scopes

• cbpii
• pisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.6.2/payment-requests/{paymentRequestResourceId}

paymentRequests

Résumé

Retrieval of a payment request (PISP)

Description

Description
The following use cases can be applied:
– retrieval of a payment request on behalf of a merchant
– retrieval of a transfer request on behalf of the account’s owner
– retrieval of a standing-order request on behalf of the account’s owner The PISP has previously sent a Request through a POST command.
– The ASPSP has registered the Request, updated if necessary the relevant identifiers in order to avoid duplicates and returned the location of the updated Request.
– The PISP gets the Request that was updated with the resource identifiers, and eventually the status of the Payment/Transfer Request and the status of the subsequent credit transfer. ### Prerequisites
– The TPP was registered by the Registration Authority for the PISP role
– The TPP was provided with an OAUTH2 « Client Credential » access token by the ASPSP (cf. § 3.4.2).
– The TPP has previously posted a Request which was saved by the ASPSP (cf. § 4.5.3) – The ASPSP has answered with a location link to the saved Payment/Transfer Request (cf. § 4.5.4)
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its « OAUTH2 Client Credential » access token ### Business flow
The PISP asks to retrieve the Payment/Transfer Request that was saved by the ASPSP. The PISP uses the location link provided by the ASPSP in response of the posting of this request.
The ASPSP returns the previously posted Payment/Transfer Request which is enriched with:
– The resource identifiers given by the ASPSP
– The status information of the Payment Request and of the subsequent credit transfer
The status information must be available during at least 30 calendar days after the posting of the Payment Request. However, the ASPSP may increase this availability duration, based on its own rules.

Scopes

• cbpii
• pisp

Paramètres

Codes retour

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

/stet/psd2/v1.6.2/payment-requests

paymentRequests

Résumé

Payment request initiation (PISP)

Description

### Description
The following use cases can be applied:
– payment request on behalf of a merchant
– transfer request on behalf of the account’s owner
– standing-order request on behalf of the account’s owner
#### Data content
A payment request or a transfer request might embed several payment instructions having
– one single execution date or multiple execution dates – case of one single execution date, this date must be set at the payment level – case of multiple execution dates, those dates must be set at each payment instruction level
– one single beneficiary or multiple beneficiaries – case of one single beneficiary, this beneficiary must be set at the payment level – case of multiple beneficiaries, those beneficiaries must be set at each payment instruction level
Having at the same time multiple beneficiaries and multiple execution date might not be a relevant business case, although it is technically allowed.
Each implementation will have to specify which business use cases are actually supported.
A standing order request must embed one single payment instruction and must address one single beneficiary.
– The beneficiary must be set at the payment level
– The standing order specific characteristics (start date, periodicity…) must be set at the instruction level Payment request can rely for execution on different payment instruments:
– SEPA Credit Transfer (SCT)
– Domestic Credit Transfer in a non-Euro-currency
– International payment
The following table indicates how to use the different fields, depending on the payment instrument: | Structure | SEPA payments | Domestic payments in non-euro currency | International payments |
| ——— | ————- | ————————————– | ———————- |
| PaymentTypeInformation/InstructionPriority (payment level) | « HIGH » for high-priority SCT, « NORM » for other SCT, Ignored for SCTInst | « HIGH » for high-priority CT, « NORM » or ignored for other CT | « HIGH » for high-priority payments, « NORM » or ignored for other payments |
| PaymentTypeInformation/ServiceLevel (payment level) | « SEPA » for SCT and SCTInst | ignored | ignored |
| PaymentTypeInformation/CategoryPurpose (payment level) | « CASH » for transfer request, « DVPM » for payment request on behalf of a merchant || « CORT » for generic international payments, « INTC » for transfers between two branches within the same company, « TREA » for treasury transfers |
| PaymentTypeInformation/LocalInstrument (payment level) | « INST » pour les SCTInst, otherwise ignored | Ignored or valued with ISO20022 external code ||
| RequestedExecutionDate (at transaction level) | Optional. if set by the PISP, it indicates the date on debit on the ordering party account. If not set by the PISP, this requests the ASPSP to execute the payment instruction as soon as possible. |||
| EndToEndIdentification (at transaction level) | Mandatory | Optional ||
| UltimateDebtor (at transaction level) | Optional |||
| UltimateCreditor (at transaction level) | Optional |||
| InstructedAmount (at transaction level) | Mandatory || Mandatory and exclusive use of one of these structures |
| EquivalentAmount (at transaction level) | Not used || Mandatory and exclusive use of one of these structures |
| ChargeBearer (at transaction level) | « SLEV » for SCT and SCTInst | « SLEV » or « SHAR » | « CRED », « DEBT » or « SHAR » |
| Purpose (at transaction level) | Optional |||
| RegulatoryReportingCode (at transaction level) | Not used | Mandatory (possibly multiple values) |
| InstructionForCreditorAgent (at transaction level) | Not used || Optional (possibly multiple values) |
| RemittanceInformation | Mandatory. Structured or unstructured, depending on the local rules and constraints |||
| Debtor (at payment level) | Mandatory, 2 address lines only | Mandatory, 4 address lines only | Mandatory. Complete strustured address can be used. |
| DebtorAccount (at payment level) | Optional | Optional. Account currency may be specified ||
| DebtorAgent (at payment level) | Optional |||
| Creditor (at transaction level) | Mandatory, 2 address lines only | Mandatory, 4 address lines only | Mandatory. Complete strustured address can be used. Date and place of birth must be specified |
| CreditorAccount (at transaction level) | Mandatory | Mandatory. Account currency may be specified ||
| CreditorAgent (at transaction level) | Optional |||
| ClearingSystemId et ClearingSystemMemberId (at transaction level) | Not used || Optional |
| IntermediaryAgent et IntermediaryAgentAccount (at transaction level) | Not used | Optional || #### Prerequisites for all use cases
– The TPP was registered by the Registration Authority for the PISP role
– The TPP was provided with an OAUTH2 « Client Credential » access token by the ASPSP (cf. § 3.4.2).
– The TPP and the ASPSP have successfully processed a mutual check and authentication
– The TPP has presented its « OAUTH2 Client Credential » access token ^{# Business flow}
## Payment Request use case
The PISP forwards a payment request on behalf of a merchant.
The PSU buys some goods or services on an e-commerce website held by a merchant. Among other payment method, the merchant suggests the use of a PISP service. As there is obviously a contract between the merchant and the PISP, there is no need for the ASPSP to check the existence of such a contract between the PSU and this PISP to initiate the process.
Case of the PSU that chooses to use the PISP service:
– The merchant forwards the requested payment characteristics to the PISP and redirects the PSU to the PISP portal.
– The PISP requests from the PSU which ASPSP will be used.
– The PISP prepares the Payment Request and sends this request to the ASPSP.
– The Request can embed several payment instructions having different requested execution date.
– The beneficiary, as being the merchant, is set at the payment level. ##### Transfer Request use case The PISP forwards a transfer request on behalf of the owner of the account. – The PSU provides the PISP with all information needed for the transfer. – The PISP prepares the Transfer Request and sends this request to the relevant ASPSP that holds the debtor account. – The Request can embed several payment instructions having different beneficiaries. – The requested execution date, as being the same for all instructions, is set at the payment level. ##### Standing Order Request use case The PISP forwards a Standing Order request on behalf of the owner of the account. – The PSU provides the PISP with all information needed for the Standing Order. – The PISP prepares the Standing Order Request and sends this request to the relevant ASPSP that holds the debtor account. – The Request embeds one single payment instruction with – The requested execution date of the first occurrence – The requested execution frequency of the payment in order to compute further execution dates – An execution rule to handle cases when the computed execution dates cannot be processed (e.g. bank holydays) – An optional end date for closing the standing Order

Scopes

• cbpii
• pisp

Paramètres

Codes retour

Entrées

application/json

Sorties

application/hal+json; charset=utf-8

application/json; charset=utf-8

Authentifications disponibles

OAuth 2.0

Comment récupérer son jeton d'accès OAUTH2 ?

1- Vous envoyez directement une requête vers l’infrastructure informatique d’autorisation de la banque teneuse de compte, le détail des liens et des paramètres se trouvent ci-après :

2 -La banque teneuse de compte (ASPSP) va effectuer des vérifications liées à votre profil en tant que TPP (validité des certificats et de votre rôle dans le référentiel de place, non révocation de votre profil, etc…).

3 -Une fois ces vérifications effectuées et si elles sont concluantes, la banque va vous répondre via un code HTTP200 (OK) et les données suivantes :

Le jeton d’accès doit être utilisé dans toutes les requêtes au niveau du header « Authorization » préfixé par le type de jeton « Bearer ». Si le jeton a expiré, la requête sera rejetée avec un code HTTP400 et des données indiquant « Token invalide ». Cette requête pourra être renvoyée une fois un nouveau jeton d’accès de type Client Credential demandé et obtenu. A noter que la durée de vie maximale d’un jeton d’accès est de 180 jours calendaires.

4 requêtes du prestataire de service initiateur de paiements

Le Prestataire de service de paiement possédant le rôle de PISP peut effectuer 4 requêtes auprès de la banque teneur de compte (ASPSP) du client débité (PAO).

POST /payment-requests

Cette méthode permet d’envoyer à l’ASPSP toutes les informations nécessaires pour effectuer un paiement. Le paiement peut avoir été demandé par le bénéficiaire (par exemple, le marchand ou PSU) ou par le titulaire du compte lui-même (le PAO).

GET /payment-requests

Cette méthode permet d’obtenir les données de l’initiation de paiement enrichies du statut de l’initiation et du paiement.

PUT /payment-requests

Cette méthode permet d’envoyer à l’ASPSP une demande de modification d’une demande d’initiation de paiement déjà enregistrée, à condition que le paiement n’ait pas encore été exécutée. Cette méthode n’étant pas encore disponible, l’appel à cette requête renverra un code HTTP 405.

POST /payment-requests

Cette méthode, liée au mode d’authentification dit « embedded », permet de confirmer la demande de paiement ou d’annulation de la demande de paiement à l’ASPSP en transmettant un facteur d’authentification du titulaire du compte débité afin que l’ASPSP puisse poursuivre la demande. Cette méthode n’étant pas encore disponible, l’appel à cette requête renverra un code HTTP 405.

Initier un paiement

Envoyer une demande d’initiation de paiement unique en €

Contexte

Cet appel permet d’envoyer à la banque teneur de compte (ASPSP) d’un client d’une banque (PAO) une demande d’initiation de paiement venant débiter le compte du PAO pour créditer le compte de l’usager du service de paiement (PSU) pour lequel le Prestataire de service de paiement (PISP) est connecté.

Dans un premier temps, seule l’initiation de paiement unique en euros est acceptée dans nos traitements.

A la soumission de la requête, et si toutes les données sont correctement formatées, une réponse (HTPP 201) vous sera retournée.

Prérequis

Pour procéder à cette requête il est nécessaire de remplir les prérequis d’éligibilité pour le rôle TPP « PISP » (voir la section « Eligibilité« ), et d’avoir récupéré le jeton d’accès OAUTH2.

Requête POST

Le point d’entrée dépendra du code établissement.

Vous devez insérer la même valeur du paramètre <cdetab> que celle utilisée pour le jeton d’accès.

Pour rappel, la liste de nos établissements et les valeurs possibles des <cdetab> sont précisées dans la section « Limitations », cf. extrait ci-dessous :

Nous avons par exemple :

• POST https://www.30007.live.api.89c3.com/stet/psd2/v1.6.2/payment-requests pour initier un paiement pour un client de Natixis CIB en production

• POST https://www.30021.live.api.89c3.com/stet/psd2/v1.6.2/payment-requests pour initier un paiement pour un client de Natixis CIB en sanbdox

Paramètres obligatoires ou facultatifs du body

La structure du body et les champs obligatoires sont décrits dans la norme STET.

Les informations suivantes doivent être valorisées dans la requête comme suit :

• La donnée serviceLevel doit être renseigné à SEPA

• La donnée currency doit être renseignée à EUR (pas de virements en devises)

• La donnée requestedExecutionDate doit être égale ou supérieure à la date du jour

• La requête doit contenir une demande d’initiation pour un seul paiement

• La donnée numberOfTransactions doit être valorisée à « 1 »

• La donnée executionRule doit être valorisée à « FWNG–following » (exécution le premier jour ouvré suivant) pour préciser les corrections de date d’exécution des paiements, si la date de traitement tombe un week-end ou un jour fermé pour la banque

• La donnée frequency ne doit pas être alimentée, les virements récurrents n’étant pas autorisés

• La donnée localInstrument ne doit pas être valorisée, seuls les SCT étant acceptés pour le moment

• Seuls les IBAN sont supportés pour les données « Iban« , « debtorAccount » et « creditorAccount« 

• La donnée « successfullReportUrl » est obligatoire pour le mode d’authentification REDIRECT mis en oeuvre

• Si la donnée « unsuccessfullReportUrl » n’est pas renseignée, c’est la donnée valorisée au niveau de « successfullReportUrl » qui sera utilisée

• La donnée supplementaryData doit être alimentée avec la valeur « REDIRECT »

• La donnée scaHint est ignorée pour l’instant => les exemptions d’AF ne seront pas possibles en 2020

• Le format autorisé pour la donnée creationDateTime est le format ISO8601. Les trois expressions régulières autorisées sont
  • YYYY-MM-DDTHH:MM:SS.SSS+HH:MM
  • YYYY-MM-DDTHH:MM:SS.SSS+HHMM
  • YYYY-MM-DDTHH:MM:SS.SSS
  • Exemples :
    • 2019-11-12T00:00:00.000+02:00
    • 2019-11-12T00:00:00.000+0200
    • 2019-11-12T00:00:00.000

Codes erreur

Exemple

Requête : POST /stet/psd2/v1.6.2/payment-requests

Body :
{ « creationDateTime »: « 2019-03-13T12:56:11.122Z », »numberOfTransactions »: 1, « paymentInformationId »: « 123456789ABCD », « paymentTypeInformation »: { « categoryPurpose »: « CASH », « instructionPriority »: « HIGH », « serviceLevel »: « SEPA », « localInstrument »: « INST » }, « purpose »: « ACCT », « beneficiary » : { « creditor »: { « name »: « John Doe », « postalAddress »: { « addressLine »: [ « 10 rue de la Rue », »75001 Paris » ], « country »: « FR » }, « privateId »: { « identification »: « 12345678900 », « issuer »: « FR », « schemeName »: « SREN » } }, « creditorAccount »: { « iban »: « FR7613825002000800000123456 »

},

« creditorAgent »: { « bicFi »: « CEPAFRPP670 » }, « id »: « string », « isTrusted »: false }, « debtor »: { « name »: « Janette Rees », « postalAddress »: { « addressLine »: [ « 12 rue de la DSP2″, »75006 Paris » ], « country »: « FR » }, « privateId »: { « identification »: « 1447114700 », « issuer »: « FR », « schemeName »: « COID » } }, « debtorAccount »: { « iban »: « FR353000799999A40166510BB25 » }, « debtorAgent »: { « bicFi »: « NATXFRPPXXX » }, « initiatingParty »: { « name »: « Small Heath », « organisationId »: { « identification »: « 00987654321 », « issuer »: « FR », « schemeName »: « BANK » }, « postalAddress »: { « addressLine »: [ « 92 rue de la Banque », »75000 Paris » ], « country »: « FR » } }, « booking »: false, « chargeBearer »: « SLEV », « requestedExecutionDate »: « 2023-03-13T12:56:11.122Z », « creditTransferTransaction »: [ { « instructedAmount »: { « amount »: « 100 », « currency »: « EUR » }, « paymentId »: { « endToEndId »: « 987654321DCBA », « instructionId »: « DCBA987654321 » }, « regulatoryReportingCodes »: [ « string » ], « remittanceInformation »: [ « Life always finds a way » ] } ], « supplementaryData »: { « acceptedAuthenticationApproach »: [ « REDIRECT » ], « appliedAuthenticationApproach »: « REDIRECT », « scaHint »: « noScaExemption », « successfulReportUrl »: « https://www.successful.fr« , « unsuccessfulReportUrl »: « https://www.unsuccessful.fr » }}

Résultat : Status code HTTP 201

{ « appliedAuthenticationApproach »: « REDIRECT », « _links »: { « consentApproval »: { « href »: « TPPPISPurlConsentApproval/psuId.html?resourceId=0000000180-1551358254000131359238543&nonce=Id-2ed9775ce61639e9a3c94ecc », « templated »: null } }}

Utiliser le fallback

Principe

Conformément à la réglementation, les établissements du Groupe BPCE ont mis en place une interface dédiée aux prestataires de services de paiement : il s’agit des API REST DSP2 publiées.

Si l’infrastructure de production « passerelle 89C3 API Live » exposant les API DSP2 est défaillante, le prestataire des services de paiements pourra utiliser la solution couvrant les « mesures d’urgence applicables à une interface dédiée » (ou « fallback ») dont le principe est le suivant :

Cette solution répond aux exigences règlementaires de la DSP2 (article 33 des RTS). Vous pourrez l’utiliser avec les mêmes conditions et pré-requis décrits dans la rubrique « Eligibilité« .

Roadmap

Retrouvez ci-dessous les éléments de notre trajectoire prévisionnelle :

(*) Fonctionnalités Principales :

• Utilisation par le TPP du même endpoint que l’interface dédiée.

• Un paramètre de requête (header « fallback:1 » présent ou absent) ajouté par le TPP permet de distinguer une requête « Fallback » d’une requête API via l’interface dédiée qui doit être utilisée systématiquement

• Authentification du TPP via authentification mutuelle TLS par un certificat eIDAS (QWAC)

• Sécurisation identique à celle d’un accès à la banque en ligne du PSU (même interface utilisée par le PSU qu’en accès direct, et mêmes moyens d’authentification du client)

• Dans le cadre de la montée en charge de l’usage de l’interface dédiée (API), il n’est pas mis en place de bascule dynamique : la solution fallback est toujours active

• La solution de fallback est une solution de secours ne devant pas être utilisée comme moyen principal d’accès pour proposer les services DSP2. Son usage en est monitoré et tout usage abusif par un/des TPP sera automatiquement reporté auprès de l’autorité nationale compétente.

Exemple

1. Dans le cas où les API DPS2 sont indisponible de façon imprévue ou le système tomberait en panne (voir critères dans le texte RTS Art. 33), le TPP peut alors envoyer la requête :

POST https://www.17515.live.api.89c3.com/stet/psd2/oauth/token

avec :

• son certificat eIDAS QWAC de production

• le paramètre header (fallback: »1″)

POST /stet/psd2/oauth/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

X-Request-ID: 1234

fallback: 1

User-Agent: PostmanRuntime/7.16.3

Accept: */*

Cache-Control: no-cache

Host: www.17515.live.api.caisse-epargne.fr

Accept-Encoding: gzip, deflate

Content-Length: 67

Connection: keep-alive

client_id=PSDFR-ACPR-12345&grant_type=client_credentials&scope=aisp

2. Si les vérifications sont positives, nous allons vous renvoyer dans le header une url de type à utiliser dans le cadre de la redirection vers l’environnement de la banque en ligne, et qui contient un jeton JWT (champs « &fallback= ») qui doit être aussi utilisé dans ce cadre :

HTTP/1.1 302 Found

Date: Tue, 25 May 2021 21:46:59 GMT

Location: https://www.caisse-epargne.fr/se-connecter/sso?service=dei&cdetab=17515&fallback=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImhF…

Content-Length: 870

Connection: close

Content-Type: text/html; charset=iso-8859-1

</head><body>

<h1>Found</h1>

<p>The document has moved <a >here</a>.</p>

</body></html>

3. Une fois redirigé, le TPP doit utiliser ensuite les identifiants du PSU via sa méthode propriétaire

Pour plus de détails sur la requête POST, voir spécifications STET

Limites

Les contraintes de cette solution sont les suivantes :

• Pas de réutilisation du contexte de l’interface dédiée, ni du jeton d’accès (valable 180 jours actuellement)

• Seules les fonctionnalités DSP2 présentes sur la banque en ligne (référence: banque à distance sur internet fixe) sont accessibles via le fallback. Par exemple, les services de banque en ligne ne proposent pas de paiement e-commerce (cette fonctionnalité PISP n’est donc pas disponible en mode fallback)

• Le client utilisateur des services (PSU) doit être connecté à l’application du TPP (pas de possibilité de traitement batch AISP pour venir récupérer les données consenties du client). La DSP2 imposant également un renforcement des moyens d’authentification forte (AF/SCA) systématique pour les accès à la banque à distance/en ligne, les moyens d’authentification fournis aux clients PSU seront utilisés (liste non exhaustive) :
  • Soft token Sécur’Pass
  • OTP SMS
  • Clé physique (pour les entreprises)

Assemblage Sandbox

Introduction – précisions sur les fonctionnalités de la sandbox

La sandbox 89C3 API peut être utilisée directement via l’application du TPP en appelant l’API « Initiation de paiement » de la plateforme 89C3 API.

En assemblage sandbox, il y a deux types d’appel :

• Le premier pour récupérer le jeton d’autorisation (voir la rubrique « Vue d’ensemble » > « Récupérez votre jeton« ) ;
• Le second pour faire l’appel à l’API DSP2 « Initiation de paiement » (voir les cas d’usage « Initier un paiement« , « Récupérer le statut « , « Confirmer une initiation » et « Annuler une initiation »).

Prérequis

Le TPP doit déclarer son APP en sandbox via notre API Register.

Rappel : en tant que TPP, vous devez être accrédité par l’une des autorités compétentes nationales européennes (ACPR en France) pour le rôle d’initiateur de paiement (« PISP »).

Le point d’entrée dépendra du code établissement <cdetab> :

Nous avons par exemple :

• POST https://www.30021.live.api.89c3.com/stet/psd2/v1.6.2/payment-requests pour initier un paiement pour un client de Natixis CIB en sanbdox

Limitations

• Le cas d’usage « Annuler une initiation de paiement », n’est pas totalement testable dans l’environnement sandbox car cette méthode nécessite un croisement des données dynamiques alors que notre sandbox a un comportement statique

• En conséquence, les requêtes d’annulation d’une initiation de paiement sont acceptées dès que le format de la requête est correct (l’identifiant de l’initiation de paiement étant supposé exister).

L’application du TPP consommatrice de l’API « Initiation de paiement » en assemblage sandbox va devoir récupérer un jeton d’accès via sa clé d’authentification auprès de l’AS (Authentification Server).

Ainsi l’application TPP pourra consommer les méthodes « POST /payment-requests« , « GET /payment-requests/{paymentRequestRessourceId}« , « POST /payment-requests/{paymentRequestRessourceId}/confirmation » et « PUT /payment-requests/{paymentRequestRessourceId} » grâce à son jeton d’accès.

Données de tests

Cette page présente les jeux de données qui permettent de tester l’API :

• Les clients fictifs proposés par NATIXIS Global Trade sont des clients corporates

• Les caractéristiques de leurs comptes y sont déclinées (mono-compte, multi-comptes, solde du compte)

• Les données utiles attendues en entrée par les API y sont énumérées (identifiant Portail Natixis Global Trade, IBAN)

Gérez les erreurs

Voici la liste de descriptions des codes erreurs pour chaque méthode (il y a une annotation en rouge pour ceux étant recensés dans la norme définie par le CFONB (Codification CFONB) :

• Obtenir la liste des comptes : get/accounts

• Obtenir la liste des soldes : get/accounts/{accountRessourceId}/balances

• Obtenir la liste des transactions : get/accounts/{accountRessourceId}/transactions

Historique des versions

Version de la norme STET utilisée pour l’API

Cette API REST est conforme à la spécification interbancaire française STET (https://www.stet.eu/en/psd2/), version v.1.6.2.0, afin de répondre aux exigences règlementaires de la DSP2. Elle tient compte des limitations fonctionnelles à l’ASPSP telles que décrites dans la section « Limitations ».

Pour rappel :

• les textes de la directive de paiement numéro 2 (DSP2, référence UE 2015/2366 du 25/11/2015) sont rentrés en application le 13 janvier 2018 : http://eur-lex.europa.eu/legal-content/FR/TXT/?uri=CELEX:32015L2366

• ils ont été complétés par les normes techniques de réglementation (NTR, règlement délégué UE 2018/389) relatives à l’authentification forte du client et à des normes ouvertes communes et sécurisées de communication dont la date d’application se situe au 14 septembre 2019. Ces normes sont les 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

En France, l’ordonnance n° 2017-1252 du 9 août 2017 transpose la directive DSP2 dans la partie législative du code monétaire et financier. L’ordonnance est complétée au plan réglementaire par les décrets n° 2017-1313 et n° 2017-1314 du 31 août 2017 et les cinq arrêtés du 31 août 2017.

Description du support

Conformément à l’article 30 (5) des RTS, une assistance pour les prestataires PSP tiers est mise à disposition. Ce support est accessible via le formulaire sur ce portail 89C3 API, ou via https://www.api.89c3.com/fr/nous-contacter. Les réponses se font pendant les heures de travail ouvrées.

Le principe général du support est schématisé ci-dessous en prenant en compte les délais réglementaires prévus à l’article 30 (4) des RTS :

Versionning de l’API

Vous pouvez consulter la FAQ au sujet des textes de la norme STET.

Roadmap

Politique de décommissionnement des versions de l’API

La politique du décommissionnement (= arrêt d’une version d’une API sur les environnements de production et sandbox) est fonction du cycle de vie des API, et il est prévu une phase de tuilage entre deux versions majeures d’API comme indiqué dans le schéma ci-dessous :

La communication du décommissionnement d’une version N se fera à la date de déploiement de la version N+1. Le canal de communication privilégié est le portail 89C3 API dans la partie « Roadmap » de l’API impactée. Une communication via courriel vers les correspondants des prestataires enrôlés sur le portail 89C3 API pourra venir compléter ce dispositif.

Planning des évolutions fonctionnelles à venir de l’API

L’API d’Information sur compte fait l’objet d’améliorations et d’évolutions continues tout au long de l’année*.

(*) NB : l’article 30 (4) des RTS précise que des changements significatifs de l’API peuvent intervenir sans délai. Nous appliquons cette clause dans les cas suivants :

• problème bloquant impactant de façon généralisée au moins l’un des segments de clients majeur (particuliers, professionnels, entreprises),
• problème de sécurité,
• évolutions demandées par les autorités nationales compétentes pour répondre à la trajectoire réglementaire.

Retrouvez ci-dessous notre roadmap prévisionnelle :

Limitations

Limitations fonctionnelles

Les limitations de cette API DSP2 sont les suivantes :

• Applicable à tous les clients Natixis CIB avec l’abonnement en ligne permettant un accès au service d’initiation de paiement adhoc
• Ne s’applique qu’aux comptes paiement des clients (cf. texte de la Directive DSP2)
• Les demandes d’initiation de paiement sont limitées à un paiement SCT CORE (immediat ou différé, non instantané)
• Le bénéficiaire d’une demande d’initiation de paiement doit être référencé dans la liste des bénéficiaires du client Natixis GTB
• Les ordres permanents et récurrents ne sont pas acceptés
• Les demande de paiement au-delà des 30 jours ne sont pas acceptées
• N’utilise que le mode d’authentification par redirection (Authentification Forte du client demandée et gérée via la banque)

• Le champ chargeBearer est obligatoire pour la méthode POST /payment-requests (ainsi que pour les suivantes) et doit être valorisé à « SLEV »

• Le champ categoryPurpose est obligatoire pour la méthode POST /payment-requests (ainsi que pour les suivantes)

• Le champ creditorAccount est obligatoire pour la méthode POST /payment-requests (ainsi que pour les suivantes)

• Le champ successfulReportUrl est obligatoire pour la méthode POST /payment-requests (ainsi que pour les suivantes)

Une seule app consommatrice peut être déclarée à ce jour par le TPP (même OID = client_Id) sachant qu’il y a possibilité de gérer :

• les modèles de partenariat en marque blanche et en tiers-utilisateur

• plusieurs certificats par app consommatrice / client_Id TPP et plusieurs URL de redirection

Limitations techniques

[Nom des champs dans la norme STET]

Accès aux données de production

Le code établissement (<codetab>) vous permet d’adresser le bon référentiel client via un « endpoint » au format www.<codetab>.live.api.89c3.com (ou www.<codetab>.live.api.natixis.com).

Eligibilité

Les ressources de l’API « Initiation de paiements » ne peuvent être consommées que par des PSP ayant le rôle de Prestataires de Services d’initiation de Paiement (PISP). Ce statut est délivré par les autorités financières du pays dans lequel la demande est effectuée ; en France il s’agit de l’Autorité de Contrôle Prudentiel et de Résolution (ACPR), liée à la Banque de France.

L’obtention et la conservation d’un agrément relèvent de procédures rigoureuses afin d’apporter des garanties fortes aux utilisateurs des services de paiements, les formulaires étant disponibles sur le site de l’ACPR : https://acpr.banque-france.fr/autoriser/procedures-secteur-banque/tous-les-formulaires.

Une fois l’agrément donné, le format de cet identifiant (Organisation Identifier = OID) fourni par l’autorité compétente est :

PSDXX-YYYYYYYY-ZZZZZZZZ:

XX =>code ISO 3166 du pays de l’autorité compétente hyphen-minus « – » (0x2D (ASCII), U+002D (UTF-8))YYYYYYYY => 2-8 caractères du l’identifiant de l’autorité compétente (A-Z, pas de séparateur)hyphen-minus « – » (0x2D (ASCII), U+002D (UTF-8))ZZZZZZZZ => identifiant du PSP spécifié par l’autorité nationale compétente (sans restriction sur le nombre – ou sur le type – de caractère utilisé)

Cet identifiant OID est important à 2 titres :

• il servira à vous identifier lors des appels dans les requêtes des API STET (via le paramètre « client_id »)

• il devra être présent dans les certificats eIDAS que vous fournirez au teneur de compte (voir ci-dessous)

De plus, vous devez disposer de certificats délivrés par une autorité de certification reconnue (Qualified Certification Service Providers – QTSP: https://webgate.ec.europa.eu/tl-browser/#/) conformes au règlement eIDAS (electronic IDentification And trust Services : https://www.ssi.gouv.fr/entreprise/reglementation/confiance-numerique/le-reglement-eidas/) et respectant la norme ETSI (https://www.etsi.org/deliver/etsi_ts/119400_119499/119495/01.02.01_60/ts_119495v010201p.pdf).

Afin de consommer les API DSP2 proposées sur ce portail, le TPP doit enrôler son app et nous transmettre via notre API Register des certificats de production signés par une autorité de certification agréée (AC) :

• un premier jeu de certificats QWAC (pour l’authentification mutuelle TLS) et QSEALC (à charger sur notre passerelle via l’API Register) pour la sandbox

• un autre jeu de certificats QWAC (pour l’authentification mutuelle TLS) et QSEALC (à charger sur notre passerelle via l’API Register) pour la production

NB IMPORTANT : en cas de renouvellement de certificat, et si l’autorité de certification (QTSP) est différente (ou c’est la même entreprise QTSP mais qui utilise des clés racines différentes), le TPP doit avertir le support API disponible via ce site de 2 mois avant à toutes fins de vérifier que les éléments de la nouvelle AC sont bien chargés sur nos infrastructures.

Un identifiant keyID devra aussi être fourni dans un format conforme à la spécification STET intégrant une empreinte SHA256 après le caractère « _ » char, voir exemple dans la documentation STET Part 3 / Interaction Exemples : keyId=https://path.to/myQsealCertificate_612b4c7d103074b29e4c1ece1ef40bc575c0a87e.

Seules les clés publiques au format .pem sont nécessaires. Des contrôles sur les données des certificats seront effectués à partir des registres Français (REGAFI : https://www.regafi.fr) et Européen (ABE ou EBA : https://euclid.eba.europa.eu/register/pir/disclaimer).