Annuler une initiation de paiement 

➤ Cas d'usage

Cette méthode permet au PISP d'annuler une demande d'initiation de paiement déjà enregistrée, à condition que le paiement n'ait pas encore été exécuté et que sa date d’exécution n’est pas atteinte (i.e. date d’exécution prévue au moins à J+1 par rapport à la date de demande d’annulation).

Autrement dit, cet appel permet d'envoyer à la banque (ASPSP) d'un client une demande d'annulation d'un paiement qui a été initié avec la méthode POST /payment-requests (voir la rubrique "Cas d'usage" > "Initier un paiement") et qui n'est pas encore échu.

Seule l’annulation d'un paiement SCT différé unique en euros est possible.

Réciproquement, et uniquement pour les Banques Populaires, la Banque de Savoie et la Banque Palatine, un virement SCT qui a été initié via l’API DSP2 PISP (quelle que soit la version) est annulable uniquement via l’API DSP2 PISP. Autrement dit, on ne peut pas annuler sur l’application internet Banque Populaire (Cyber) ou l’application mobile Banque Populaire un virement SCT qui a été initialisé via DSP2.

 

➤ 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").

Le TPP a déjà envoyé une requête qui a été enregistrée par l'ASPSP et à laquelle l'ASPSP a répondu avec un lien de localisation vers la demande de paiement / virement sauvegardée.

 

➤ Requête

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

Vous devez utiliser 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", cf. extrait ci-dessous :

Code établissement <cdetab>Nom de l'établissementNom abrégé
13807 B.P Grand Ouest BPGO
17515 CE Ile de France  CEIDF

 

En exemple, voici la requête pour annuler un paiement pour un client de la BPGO en production :

PUT https://www.13807.live.api.89c3.com/stet/psd2/v1/payment-requests/{paymentRequestResourceId}

 

➤ Paramètres obligatoires ou facultatifs du body requis pour l'appel de ce service

Paramètre obligatoire paymentRequestResourceId : identifiant de la requête d'initiation de paiement pour laquelle on souhaite annuler le virement.

La structure du body et les champs obligatoires sont décrits dans la norme STET. Le Tiers de Paiement peut et doit récupérer les informations de son virement avec la méthode GET /stet/psd2/v1/payment-requests/{paymentRequestResourceId} afin de vérifier que le paiement est à un statut annulable. 

Pour savoir si un virement est éligible les informations suivantes doivent être valorisées dans la requête comme suit :

  • La donnée paymentInformationStatus doit aveoir la valeur :
    • ACSP
  • La donnée transactionStatus (au niveau de la transaction dans l’objet creditTransferTransaction) doit avoir la valeur : 
    • PDNG
  • La donnée serviceLevel doit être renseigné à SEPA (seule les virements SEPA différés sont annulables)
  • La donnée currency doit être renseignée à EUR => les virements internationaux en devise ne sont pas disponibles
  • La requête doit contenir un seul paiement
  • La donnée numberOfTransactions doit être valorisée à "1"
  • La donnée frequency ne doit pas être alimentée, les virements récurrents se sont pas autorisés pour le moment => cette fonctionnalité sera disponible au 01T 2021
  • La donnée localInstrument ne doit pas être valorisée, seuls les SCT étant acceptés pour l'annulation
  • La donnée requestedExecutionDate doit être dans le futur : à minima à J+1

 

Pour permettre à la banque de comprendre que la requête est une demande d'annulation d'une initiation de paiement, certaines informations doivent être modifiées dans la requête comme suit (API DSP2 STET_V1.4.0.47 Part 3 Interaction Examples p.27) :

  • La donnée transactionStatus(au niveau de la transaction dans l’objet creditTransferTransaction) doit être positionnée à "RJCT" (Rejeté)
  • La donnée statusReasonInformation(au niveau de la transaction dans l’objet creditTransferTransaction) doit être positionnée à "DS02" (Annulation client)
  • Il faut également enlever toute la partie _links
  • Pour finir il faut supprimer l'intitulé du parent "paymentRequest": {" ainsi que l’accolade fermante en bas du flux "}"

Les autres données de la requête doivent être identiques à celles récupérées avec la méthode GET.

 

➤ Résultat retourné

A la soumission de la requête, et si toutes les données sont correctement formatées, une réponse (HTPP 200) vous sera retournée.Cette réponse contiendra le ressourceId du 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.

Remarque : La donnée paymentRequestRessourceId, essentielle pour pouvoir annuler un paiement, est incluse en tant que paramètre dans l'URL de consentement "consentApproval" renvoyée lors de l’initiation de paiement. Idem pour le non rejeu : c'est le paramètre nonce dans l'URL de consentement.

 

➤ 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  

➤ Exemple

Requête :

PUT /stet/psd2/v1/payment-requests/00000032fa-159127166900013807464584 

Body de Demande d'annulation v1.4.0

 

{
    "resourceId": "00000032fa-159127166900013807464584",
    "paymentInformationId": "azertyui",
    "creationDateTime": "2020-06-04T13:54:29.148+02:00",
    "numberOfTransactions": 1,
    "initiatingParty": {
        "name": "Pisp Name",
        "postalAddress": {
            "country": "FR",
            "addressLine": [
                "512 rue Reaumur",
                "75512 PARIS"
            ]
        },
        "organisationId": {
            "identification": "12FR5",
            "schemeName": "COID",
            "issuer": "ACPR"
        },
        "privateId": null
    },
    "paymentTypeInformation": {
        "instructionPriority": null,
        "serviceLevel": "SEPA",
        "localInstrument": null,
        "categoryPurpose": "DVPM"
    },
    "debtor": {
        "name": "Customer Name",
        "postalAddress": {
            "country": "FR",
            "addressLine": [
                "512 rue Leclerc",
                "94512 Charenton-le-Pont"
            ]
        },
        "organisationId": null,
        "privateId": {
            "identification": "D8183250I0",
            "schemeName": "BANK",
            "issuer": "BICXYYTT512"
        }
    },
    "debtorAccount": {
        "iban": "FR7613685749843054784158595",
        "other": null
    },
    "debtorAgent": {
        "bicFi": "CCBPFRPP512",
        "clearingSystemMemberId": {
            "clearingSystemId": "clearingSystemId",
            "memberId": "memberId"
        },
        "name": "Cpy Name",
        "postalAddress": {
            "country": "FR",
            "addressLine": [
                "512 rue De Gaulle",
                "85000 LRSY"
            ]
        }
    },
    "beneficiary": {
        "id": null,
        "isTrusted": null,
        "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"
            },
            "privateId": null
        },
        "creditorAccount": {
            "iban": "FR7613825002000400000041717",
            "other": null
        }
    },
    "ultimateCreditor": null,
    "purpose": "COMC",
    "chargeBearer": "SLEV",
    "paymentInformationStatus": "ACSP",
    "statusReasonInformation": null,
    "fundsAvailability": null,
    "booking": null,
    "requestedExecutionDate": "2020-06-04T13:54:29.148+02:00",
    "creditTransferTransaction": [
        {
            "paymentId": {
                "resourceId": "00000032fa-159127166900113807942902",
                "instructionId": "instructionId 1591271669",
                "endToEndId": "endToEndId 1591271669"
            },
            "requestedExecutionDate": null,
            "endDate": null,
            "executionRule": null,
            "frequency": null,
            "instructedAmount": {
                "currency": "EUR",
                "amount": "2.12"
            },
            "beneficiary": null,
            "ultimateCreditor": null,
            "regulatoryReportingCodes": [],
            "remittanceInformation": [
                "remittanceInformation01"
            ],
            "transactionStatus": "RJCT",
            "statusReasonInformation": "DS02"
        }
    ],
    "supplementaryData": {
        "acceptedAuthenticationApproach": [
            "REDIRECT"
        ],
        "appliedAuthenticationApproach": "REDIRECT",
        "scaHint": "scaExemption",
        "successfulReportUrl": "https://www.successful.fr",
        "unsuccessfulReportUrl": "https://www.unsuccessful.fr"
    }
}

 

Résultat :

Status code : 200

 

Body de la réponse :

{
    "appliedAuthenticationApproach": "REDIRECT",
    "_links": {
        "consentApproval": {
            "href": "https://www.13807.live.api.89c3.com/89C3api/accreditation/v1/cancellation?paymentRequestRessourceId=00000032fa-159127166900013807464584&nonce=RFxE0ywQmzW0Z68xJloN&creditorName=QW1hem9uIFNB&creditorAccount=RlI3NjEzODI1MDAyMDAwNDAwMDAwMDQxNzE3&amount=Mi4xMg%3D%3D¤cy=RVVS&successfulReportUrl=aHR0cHM6Ly93d3cuYXBpLjg5YzMuY29tLmZy&unsuccessfulReportUrl=aHR0cHM6Ly93d3cuYXBpLjg5YzMuY29tLmZyL25vdXMtY29udGFjdGVy&debtorAccount=RlI3NjEzODA3MDA4MDQzMDAxOTY1NDA1MTU4&privateId=RDgxODMyNTBJMA%3D%3D&requestedExecutionDate=MjAyMC0wNi0yNFQwOTowMTozMy44NTQrMDI6MDA%3D&method=UFVU",
            "templated": true
        }
    }
}