Initier un paiement
Envoyer une demande d'initiation de paiement en € !
➤ Contexte
Cet appel permet au TPP d'envoyer à la banque (ASPSP) d'un client une demande d'initiation de paiement venant débiter son compte via un virement. S’il s’agit d’une initiation de paiement initiée par un e-commerçant (pas par le client final), le virement va créditer celui de l'usager du service de paiement (PSU) pour lequel le Prestataire de service de paiement (PISP) a été mandaté, à savoir le e-commerçant.
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.
Cette réponse contiendra le ressourceId de l'initiation de paiement, ainsi que le mode d'authentification SCA Redirect (seul mode disponible), l'URL de consentement en fonction de la banque du payeur (urlconsent_approval_URL) et le non-rejeu.
Différents types de virements sont disponibles (SCT Core immédiat, différé, permanent, instantané, mutiple), voir la section "Limitations".
Attention : toutes les demandes d'initiation de paiement ne se concluent pas automatiquement par un virement car des règles de gestion s'appliquent et peuvent rejeter la demande PIS (par exemple : règles bancaires, lutte anti-fraude, etc...). Un code STET est retouné dans ces cas.
➤ 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 rubrique "Eligibilité"), et d'avoir récupéré le jeton d'accès OAUTH2 (voir la rubrique "Vue d'ensemble" > "Récupérer un jeton").
➤ 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 rubrique "Limitations".
Pour exemple, nous avons donc comme URL pour initier en production un paiement pour un client du teneurs de compte :
POST https://www.<cdetab>.live.api.89c3.com/stet/psd2/v1.6.2/payment-requests
Paramètres obligatoires ou facultatifs du body requis pour l'appel de ce service
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ée à "SEPA"
- La donnée amount doit être renseignée avec une valeur conforme aux montants min/max tels qu'appliqués sur la banque en ligne, et qui peuvent être différents par ASPSP et/ou par type d'opération demandée (SCT CORE ou INST) et/ou par segment client
- La donnée currency doit être renseignée à EUR => les virements internationaux en devise ne sont pas disponibles
- Seuls les IBAN sont supportés pour les données Iban, debtorAccount et creditorAccount
- La donnée numberOfTransactions doit être valorisée (voir les valeurs possibles dans les paragraphes ci-dessous)
- La donnée frequency doit être valorisée que pour les virements SCT permanent (voir les valeurs possibles dans les paragraphes ci-dessous)
- La donnée localInstrument est à alimenter avec la valeur « INST » pour déclencher un SEPA Instant Payment (SCT Inst).
- Ce type de virement occasionne des frais facturés au client en fonction des conditions tarifaires en vigueur applicables pour son segment de clientèle
- La banque du bénéficiaire doit être atteignable en SCT Inst
- Pour les clients professionnels et entreprises, il faut que les les comptes émetteurs et les pays des bénéficiaires éligibles pour ce type de virement sont définis sur le contrat de banque en ligne.
- La donnée remittanceInformation doit intégrer la balise "unstructured" soit par exemple "remittanceInformation" : { "unstructured" : [ "test " ] }
- La donnée successfullReportUrl est obligatoire pour le mode d'authentification REDIRECT mis en œuvre et doit contenir :
- la redirect URL
- ainsi que le pkce : code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) + code_challenge_method = S256
- et le séparateur "&" (/!\ pas de "?")
- 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'authentification forte ne sont pas possibles
- La donnée state est obligatoire pour le mode d'authentification REDIRECT mis en œuvre car elle est propagée durant tout le parcours PISP
- Le champ endToEndId ne doit pas être vide
Le champ chargeBearer est obligatoire pour la méthode POST /payment-requests, et il doit avoir la valeur "SLEV"
Le champ categoryPurpose permet d’empêcher les virements non-marchands vers des bénéficiaires inconnus (non-enregistrés sur la banque en ligne du client) lorsque le niveau du moyen d'authentification utilisé par le client n'est pas assez élévé pour effectuer cette opération (hors Secur'pass): ce champ est nécessaire pour savoir si le paiement est un paiement "à la volée" ou non, et est obligatoire pour la méthode POST /payment-requests.
Il doit avoir la valeur "CASH" (opération de compte à compte) ou "SALA" (virement de salaire) ou "DVPM" (opération e-commerce) générant des règles de gestion différentes (voir ci-dessous)
- Le champ requestedExecutionDate doit avoir une date supérieure à la date de demande d’initiation de paiement creationDateTime
- La donnée facultative debtor.privateId.identification peut être renseignée avec le numéro abonné du PSU utilisé pour son accès direct (et avec des majuscules si un/des caratères alphanumériques sont présents)
- Le champ creationDateTime ne doit pas être vide, et rempli comme le précédent avec une des trois expressions régulières autorisées au format ISO8601 :
YYYY-MM-DDTHH:MM:SS.SSS+HH:MM
YYYY-MM-DDTHH:MM:SS.SSS+HHMM
YYYY-MM-DDTHH:MM:SS.SSS
NB : Z en fin de format signifie que l'heure est en UTC
Exemples :
2019-11-12T00:00:00.000+02:00
2019-11-12T00:00:00.000+0200
2019-11-12T00:00:00.000
Déclenchement des parcours fluides
Il est possible de déclencher un parcours fluide (avec deux variations) lorsque la requête contient des informations plus précises sur le débiteur :
- Si seul l'IBAN débiteur (debtorAccount) est fourni : déclenchement de l'identification du PSU avant une authentification forte unique en fin de parcours pour sceller le paiement
- Si l'IBAN débiteur (debtorAccount) et l'identifiant du PSU (privateId) sont fournis : déclenchement d'une authentification forte unique en fin de parcours pour sceller le paiement
Heure limite pour un virement SCT immédiat
Le CUT-OFF correspond à l’heure limite à laquelle un établissement peut exécuter un virement. Cette heure limite prend en compte :
- Les délais de traitement interne
- Les CUT-OFF des différents systèmes de compensation interbancaires, eux-mêmes assujettis au CUT-OFF des différents systèmes de règlement (généralement TARGET2)
Dans le cas des SEPA CREDIT TRANSFER (SCT), l’exécution doit être effectuée au plus tard dans la date de règlement correspondant à celle demandée par le donneur d’ordre. Il n’est pas permis de reporter cette date de règlement sauf lorsque l'heure de CUT-OFF est dépassée, l’exécution étant reportée à la date suivante possible (non fériée). Les dates d’exécution et de règlement sont donc fonction de l’heure d’arrivée de la demande d'initiation de paiement.
Pour cet ASPSP, le CUT-OFF pour demander un virement SCT à J avec une date de règlement à J est fixé à 13h30 heure locale française.
Pour rappel, l’heure locale française est égale à :
- GMT+2 pendant l’été
- GMT+1 pendant l’hiver
Valeur du champ creationDateTime | Valeur du champ requestedExecutionDate | Résultat de la prise en compte de la demande | Date d’exécution | Date de règlement |
---|---|---|---|---|
Jour de semaine | ||||
Avant 13h30 | Jour J | OK | J | J si non férié sinon jour suivant non férié |
Entre 13h30 (compris) et 23h59:59:999 | Jour J | OK | J | J+1 si non férié sinon jour suivant non férié |
Samedi (ou dimanche ou férié) | ||||
Avant 13h30 | Jour J | OK | J | lundi si non férié sinon jour suivant non férié |
Entre 13h30 (compris) et 23h59:59:999 | Jour J | OK | J | lundi si non férié sinon jour suivant non férié |
Cas du SCT unitaire
La requête doit contenir une demande d'initiation pour un seul paiement (pas de paiement multi-bénéficiaire) :
- la donnée numberOfTransactions doit être valorisée à "1"
- La donnée requestedExecutionDate doit être égale ou supérieure à la date du jour
Cas des SCT différé et permanent
La date d'exécution (donnée requestedExecutionDate) d'un virement différé (ou de la première échéance d'un virement permanent) doit être positionnée au-delà de J + 72 heures, sinon la demande sera rejetée.
Pour le SCT permanent, les fréquences (donnée frequency) possibles sont :
- hebdomadaire
- bi-mensuelle
- mensuelle
- trimestrielle
- semestrielle
- annuelle
La date de dernière échéance (donnée endDate) doit aussi être renseignée et doit correspondre à une échéance valide dans le futur.
Cas des SCT multiples
Ce type d'opération correspond à un virement d'un compte débiteur professionnel ou entreprises vers N comptes bénéficiaires. Cela se traduira ultimement par N virements unitaires vers les IBAN créditeurs.
La donnée numberOfTransactions est comprise entre 2 et 25 au plus pour un virement multiple.
Les seules valeurs autorisées du champ categoryPurpose sont "CASH" et "SALA".
Un virement multiple n’est possible qu’avec la même requestedExecutionDate pour l’ensemble des virements (mono-date d'éxécution, pas de multi-date).
La validation du virement multiples par le PSU valide l’ensemble des virements unitaires dont le transactionStatus évolue de la même manière pour l’ensemble des virements unitaires.
Si toutes les conditions sont réunies, un virement multiple se déboucle en un débit unique du PSU correspondant au montant de l’ensemble des virements unitaires produits et qui sont traités au même moment : le transactionStatus de tous les virements sera le même, ainsi que le paymentInformationStatus.
Si l’un de ces virements unitaires est rejeté par l'ASPSP avant compensation, l'ensemble du virement multiple est rejeté et le transactionStatus de ce virement passe à « RJCT », le paymentInformationStatus passe à « PART ».
Si l’un de ces virements unitaires est rejeté par la banque du bénéficiaire, le PSU est recrédité du montant de ce virement et le transactionStatus de ce virement passe à « RJCT », le paymentInformationStatus passe à « PART ».
Si tous ces virements unitaires sont rejetés par la banque des bénéficiaires, le PSU est recrédité du montant total du virement multiples, le transactionStatus de tous les virements unitaires passe à « RJCT » ainsi que le paymentInformationStatus.
Contrôle sur le bénéficiaire
Un contrôle additionnel est en place afin de rejeter la demande d’initiation de paiement :
- si le bénéficiaire est absent de la liste des bénéficiaires enregistrés par le client dans sa banque en ligne
- et si le champ categoryPurpose = "CASH" ou "SALA"
- et si le moyen d'authentification forte utilisé par le PSU n’est pas le plus sécuritaire (Sécur'Pass ou certificat physique)
➤ Codes erreur
Type d'erreur | Code HTTP | Libellé | Motif |
---|---|---|---|
Générique, mauvaise structure | 400 | Bad request | error code : FF01 message : RJCT |
Mauvais format du BIC | 400 | Bad request | error code : FF01 message : RJCT error : le champ creditorAgent.bicFi bicFi-Code allocated to a financial institution by the ISO 9362 Registration Authority as described in ISO 9362 |
Mauvais format du serviceLevel | 400 | Bad request | error code : FF01 message : RJCT error : value not one of declared Enum instance names: [SEPA, NURG] |
Mauvais format, chargeBearer autre que SLEV | 400 | Bad request | error code: FF01 message: RJCT error: value not one of declared Enum instance names: [SLEV] |
Mauvais format du schemeName | 400 | Bad request | error code: FF01 message : RJCT error : le champ creditor.privateId.schemeName schemeName-Possible values BANK,COID,SREN,DSRET,NIDN,OAUT,CPAN |
Mauvais format du purpose | 400 | Bad request | error code: FF01 message: RJCT error: value not one of declared Enum instance names: [TRPT, CASH, CPKC, ACCT, COMC] |
Mauvais format du categoryPurpose | 400 | Bad request | error code: FF01 message: RJCT error: value not one of declared Enum instance names: [CASH, DVPM] |
Mauvais jeton d'accès, problème d'authentification | 403 | Forbidden | |
Request resource inconnu | 404 | Not Found | |
Mauvaise requête ou requête hors périmètre autorisé | 405 | Method not allowed | |
Message générique | 500 | Internal server error | |
Requête en doublon | 500 | Internal server error | error : Problème d'insertion en base de donnée, clé unique dupliquée |