Guides

Accepter des paiements et des factures

Au coeur du systeme, les paiements commencent par un montant impaye a encaisser aupres d'un client. Il est possible de construire et maintenir toute la logique de paiement de maniere independante : gerer les mandats, les maintenir a jour, stocker les tokens, generer des liens de paiement, suivre les methodes de paiement et decider quelles options montrer a quel client. Cependant, cela devient rapidement complexe et difficile a faire evoluer.

Au lieu de cela, toute cette responsabilite peut etre deleguee a Twikey en soumettant les montants impayes au endpoint de facture. Malgre son nom, le endpoint de facture ne se limite pas aux factures traditionnelles - il gere tout type de paiement : frais d'abonnement, charges ponctuelles, amendes, dons ou tout autre montant impaye. En soumettant un paiement a Twikey, Twikey prend en charge tout ce qui concerne l'encaissement :

• Proposer les methodes de paiement correctes au client
• Convertir les clients au paiement automatique lorsqu'un mandat est possible
• Gerer les mandats, tokens et liens de paiement
• Gerer differents flux de paiement en fonction de la situation du client

Les methodes de paiement et la configuration PSP sont gerees dans le tableau de bord Twikey. Lors de la creation d'un paiement, il n'est pas necessaire de savoir si le client dispose d'un mandat/token, quelle methode de paiement s'applique, ou si un mandat/token doit etre signe. Cela signifie qu'une seule integration couvre tous les flux de paiement.

Chaque flux de paiement commence par un appel au endpoint de facture : POST /creditor/invoice, et s'il y en a beaucoup, ils peuvent meme etre envoyes en un seul appel via l'insertion en lot.

A partir de ce point, Twikey determine les actions appropriees en fonction du contexte client, des mandats/tokens disponibles et de la configuration. Les sections ci-dessous decrivent les flux possibles qui peuvent suivre, et comment les suivre et les gerer via le feed de paiements.

Paiements et factures pour un client avec un mandat/token

Lorsque le client dispose deja d'un mandat/token actif, le flux est simple :

Apres la creation du paiement, Twikey initie automatiquement une transaction selon les details du mandat/token. Aucune interaction supplementaire du client n'est necessaire. Un webhook est envoye lorsque le statut du paiement change, apres quoi les details peuvent etre recuperes via le feed de paiements.

La page de paiement reflette egalement cet etat. Les methodes de paiement disponibles sont masquees et le client est informe qu'un paiement automatique est deja en cours et qu'aucune action supplementaire n'est necessaire.

Paiements et factures pour un client sans mandat/token

Lorsqu'il n'y a pas de mandat/token pour initier automatiquement une transaction, le client se voit presenter les differentes methodes de paiement activees pour le paiement. Selon la methode de paiement choisie, le flux cote Twikey sera different mais se termine par un evenement de paiement dans le feed de paiements. Une fois que le client a termine, un webhook est envoye.

Methodes de paiement disponibles

Idealement, le client signe un mandat/token pour les paiements futurs. De cette facon, les paiements se font automatiquement, reduisant les retards de paiement. Apres la signature du client, Twikey initie automatiquement le paiement du cote de la banque/du PSP.

Le traitement des paiements ponctuels est toujours le meme, quel que soit le PSP connecte a Twikey.

Bien que le virement bancaire ne soit pas recommande comme methode de paiement principale, les informations de virement peuvent etre rendues disponibles sur la page de paiement. A noter qu'une correspondance reussie ne se produit que si les informations de communication et le montant sont correctement fournis par le client.

Feed de paiements

Une fois un paiement cree, Twikey devient la source de verite pour tout ce qui arrive a ce paiement.

Au lieu d'interroger les paiements individuellement, le feed de paiements doit etre consomme. Ce feed est base sur les evenements et represente un flux chronologique d'evenements decrivant ce qui est arrive a tous les paiements depuis la derniere lecture. Cela inclut toutes les etapes : si un paiement a ete encaisse par prelevement automatique mais a depuis ete annule, les evenements payment et payment_failure seront tous deux presents dans le feed.

Non seulement tous les evenements de paiement sont disponibles, mais des informations plus detaillees peuvent etre extraites si necessaire pour l'integration :

• Quelle banque ou PSP (passerelle) a ete utilise pour le paiement
• Quel mandat/token a ete utilise
• Un code d'erreur unifie
• Les codes exacts recus de la passerelle
• La prochaine etape de suivi automatique que Twikey executera
• Ou en est le paiement dans le processus de suivi automatique

Paiements et factures en lot

Au lieu de creer des paiements un par un, plusieurs paiements peuvent etre soumis en lot. Les paiements en lot permettent de livrer plusieurs montants impayes en un seul appel API, au lieu d'une requete par paiement. C'est particulierement utile pour la facturation par lots ou les exports periodiques. Apres soumission a POST /creditor/invoice/bulk, Twikey traite le lot de maniere asynchrone. Chaque paiement est traite individuellement et suit la meme logique de paiement et le meme flux de validation qu'une requete de paiement classique.

Hebergement des documents de facture Lors de la soumission de paiements en lot, il n'est pas necessaire de charger les PDF de facture.

Au lieu de cela, le document de facture peut etre heberge en externe, avec seulement l'URL du document incluse dans la charge utile du lot. Pendant le traitement du lot, Twikey recupere et stocke automatiquement le document, de sorte que le PDF complet n'a pas besoin d'etre transmis dans l'appel API. Le document copie est ensuite utilise de maniere coherente dans toutes les communications et flux de paiement lies au paiement.

Suivi d'un traitement en lot

Une fois le traitement termine, Twikey envoie un webhook indiquant que l'importation du lot est terminee. A ce moment-la, le statut final du traitement en lot peut etre recupere via le endpoint de statut du lot. Cela permet de verifier :

• Si tous les paiements ont ete importes avec succes
• Quand arreter l'hebergement des PDF de facture en ligne

Actions sur un paiement ou une facture

Une fois un paiement cree, des actions supplementaires peuvent etre declenchees. Ces actions se repartissent en deux categories distinctes : communication et actions de paiement. Toutes ces actions utilisent la meme structure de endpoint : POST /creditor/invoice/{{id}}/{{action}}

Actions de communication

Les actions de communication sont utilisees pour re-engager le client et le guider vers le paiement.

Selon la situation, les options sont :

• Envoyer un rappel par email ou SMS
• Envoyer une lettre physique via l'un des partenaires postaux
• Reessayer l'envoi de la facture par peppol

Quel que soit le canal, chaque communication renvoie toujours a la page de paiement originale de la facture. Cela garantit que :

• Le client voit toujours l'etat actuel de la facture
• Les paiements en double sont evites
• La disponibilite des methodes de paiement reste coherente
• Il n'est pas necessaire de generer de nouvelles demandes de paiement ou de nouveaux liens

Actions de paiement Les actions de paiement sont generalement utilisees apres que la tentative de collecte initiale, le suivi et la communication associee n'ont pas abouti a un paiement reussi. Elles permettent d'intervenir sur un paiement existant sans creer une nouvelle demande de paiement. Deux approches sont possibles :

Reessayer un paiement automatique Si le client dispose deja d'un mandat ou token existant, Twikey peut etre charge de tenter un nouveau paiement automatique en utilisant ce mandat/token.

Demarrer un plan de paiement Comme alternative, un plan de paiement peut etre demarre. Lors de la creation d'un plan de paiement, les elements suivants sont attendus :

• Le nombre de versements
• Quel mandat ou token sera utilise
• Le montant initial a encaisser
• Le montant de chaque versement suivant

Twikey prend alors en charge :

• La planification des versements
• L'execution de chaque paiement sur le mandat ou token
• Le rapport de progression et de resultats via le feed de paiements

Lignes de detail

Les lignes de detail ne sont requises que lorsque Twikey doit generer un PDF ou un document UBL, par exemple pour la livraison via Peppol. Si la generation de document n'est pas necessaire, cette section peut etre ignoree.

Lors de la fourniture de lignes de detail, elles doivent etre incluses dans les donnees de la facture. Twikey applique les regles strictes de Peppol lors du traitement des lignes de facture. Cela garantit que les documents UBL generes sont valides et peuvent etre livres avec succes. Ces regles sont appliquees meme lorsque les factures ne sont pas envoyees par Peppol, assurant un comportement coherent dans toutes les integrations.

Si la specification UBL change a l'avenir, Twikey gere ces mises a jour en interne. Tant que l'integration suit les regles de lignes de detail decrites ci-dessous, aucune modification n'est necessaire. Pour les details sur la TVA et les arrondis, la page de support explique plus en profondeur comment eviter les problemes legaux.

Notes de credit et remboursements

Selon l'objectif vise, il convient de creer une note de credit ou d'emettre un remboursement sur un paiement, ou les deux, car dans Twikey l'emission d'un remboursement fonctionne differemment de l'emission d'une note de credit.

Remboursements Les remboursements sont utilises lorsque de l'argent doit etre retourne au client. Lors de la creation d'un remboursement, Twikey utilise automatiquement la methode de paiement originale et, dans la mesure du possible, execute le remboursement sur le meme mandat, token ou PSP utilise pour le paiement. Les remboursements sont des operations purement monetaires. Ils ne generent pas de documents comptables et n'affectent pas les totaux ou les etats des factures au-dela de l'annulation monetaire.

Notes de credit Les notes de credit sont utilisees pour corriger ou reduire une facture, independamment du fait que l'argent soit retourne immediatement. Les cas d'utilisation typiques des notes de credit sont :

• Generer une note de credit sous forme de PDF ou UBL (par exemple pour Peppol) et l'envoyer au client
• Reduire le montant d'une facture impayee

La creation d'une note de credit utilise le meme endpoint et les memes parametres que la creation d'une facture. La seule difference est que le montant est negatif. Une note de credit peut etre liee a une facture existante en fournissant relatedInvoiceNumber dans le corps de la requete. Cela signifie que les notes de credit s'integrent naturellement dans les flux existants de factures et de paiements sans necessiter une integration separee.

Comportement des notes de credit selon l'etat de la facture

Selon l'etat de la facture liee, Twikey se comporte differemment lors de la creation d'une note de credit.

Factures enregistrees ou expirees

• Le montant de la note de credit est deduit de la facture
• Les notes de credit partielles reduisent le montant restant a payer
• La note de credit elle-meme est immediatement marquee comme payee
• Tout solde restant sur la facture peut toujours etre encaisse
• Si le total de toutes les notes de credit liees atteint le montant total de la facture, la facture est marquee comme payee

Factures payees

• Le montant de la note de credit n'est pas deduit de la facture
• La note de credit reste a l'etat enregistre
• Aucun remboursement n'est declenche automatiquement
• Si de l'argent doit etre retourne dans ce cas, un remboursement doit etre cree separement

Mandats et tokens

Comme decrit dans la section paiements, lorsqu'un client dispose d'un mandat ou d'un token, les factures sont encaissees automatiquement sans aucune interaction du client. Les clients peuvent egalement signer des mandats directement depuis la page de paiement. Cependant, la signature et la gestion des mandats peuvent aussi etre implementees directement, permettant un controle plus fin ou une integration dans des processus existants. Lorsque les transactions sont gerees directement, la gestion du mandat est attendue.

Un mandat est une autorisation pour le prelevement automatique (SEPA CORE, SEPA B2B ou BACS), tandis qu'un token represente des details de carte stockes pour les paiements recurrents. Malgre les differences legales et fonctionnelles entre ces schemas, Twikey les unifie : ils sont crees et utilises de la meme maniere. Les flux de paiement, les flux de transactions et les actions sur les mandats fonctionnent de maniere identique quel que soit le type sous-jacent, alignant tous les schemas et simplifiant l'integration en une seule approche.

Chaque mandat ou token commence par l'un des deux endpoints : POST /creditor/invite ou Twikey gere toute l'experience de signature, ou POST /creditor/sign ou le processus de signature est controle en externe. Une fois crees, tous les changements sur les mandats et tokens, y compris les nouvelles signatures, les modifications et les annulations, sont disponibles via le feed de mandats.

Le endpoint /invite vs /sign

Il existe deux facons de creer un mandat ou un token, chacune offrant un niveau de controle different sur l'experience de signature.

Le endpoint invite Le endpoint POST /creditor/invite cree un mandat prepare (non signe) et retourne une URL de signature. Lorsque le client visite cette URL, Twikey gere toute l'experience de signature : validation des informations du client, presentation des termes et conditions, et proposition des methodes de signature configurees sur le template.

Le endpoint sign Le endpoint POST /creditor/sign contourne tous les ecrans Twikey. Cet endpoint est destine aux integrations ou l'experience de signature est entierement integree dans l'application du marchand. Etant donne que les ecrans Twikey ne sont pas affiches, la method a utiliser est attendue ainsi que toutes les donnees specifiques a la methode. Par exemple, une signature manuscrite necessite l'image de la signature, et pour eMachtiging le BIC est necessaire pour que l'ecran de selection de banque puisse etre ignore. Les termes et conditions de Twikey doivent egalement etre inclus dans les propres termes du marchand, car les ecrans d'acceptation de Twikey ne sont pas presentes au client. Pour cette raison, les liens generes au endpoint sign sont destines a etre utilises immediatement plutot qu'envoyes au client.

Importer un mandat existant L'utilisation du endpoint sign avec method=import est un cas special : cela suppose que le mandat est deja entierement signe en externe et est simplement importe dans Twikey. Cette option est disponible sur chaque template independamment des methodes de signature configurees.

Quand utiliser chaque endpoint Le endpoint invite est l'integration la plus simple : Twikey prend en charge l'experience utilisateur de signature, la validation et l'acceptation des termes. Le endpoint sign offre une liberte totale pour construire l'experience de signature dans un flux personnalise, mais avec la responsabilite de gerer les donnees specifiques a la methode, la collecte des donnees client et l'acceptation des termes.

Flux de signature client

Independamment du endpoint utilise, il existe deux modeles pour la maniere dont l'experience de signature est livree au client.

Twikey envoie l'invitation Lorsque Twikey envoie l'invitation, le lien de signature est livre par email directement au client. Cela convient bien aux conversions post-vente vers le paiement automatique ou aux campagnes de conversion en masse. Le client recoit l'email, clique sur le lien et complete le processus de signature.

Rediriger le client Au lieu de faire envoyer l'invitation par Twikey, l'URL de signature est retournee dans la reponse API et peut etre utilisee pour rediriger le client directement. C'est ideal pour les flux d'integration dans les sites web ou lorsque les communications sont envoyees via un systeme externe.

Signature via premier paiement

Dans des scenarios tels que les flux de paiement en ligne, les activations d'abonnement ou toute situation ou l'onboarding et l'encaissement ont lieu simultanement, la signature d'un mandat peut etre combinee avec l'encaissement d'un premier paiement en une seule etape. En incluant transactionAmount et transactionMessage lors de la creation du mandat, le client signe et paie en un seul flux. Etant donne que la signature via premier paiement est toujours liee a un achat reel, la validite de la signature resultante est beaucoup plus solide. Cependant, cela necessite une methode de signature qui prend en charge l'initiation via premier paiement, ou un vrai paiement est effectue via un PSP (qui capture l'IBAN ou les details de carte) ou via l'initiation de paiement (Twikey-pay-by-bank). Puisqu'un paiement est implique, deux evenements webhook sont envoyes : type=payment pour la transaction et type=contract pour le mandat signe.

Validation B2B

Les mandats de prelevement SEPA B2B different des mandats CORE en ce qu'ils necessitent non seulement la signature du client mais aussi l'enregistrement aupres de la banque du client. La facon dont cela est gere depend de la banque :

Banques connectees Pour les banques avec lesquelles Twikey a une connexion directe, l'ensemble du processus de signature et d'enregistrement est numerique et automatise. Aucune etape manuelle n'est necessaire. Le client signe le mandat et l'enregistrement bancaire est gere en arriere-plan.

Banques non connectees Pour les banques sans connexion directe, le flux de validation B2B peut etre active. Apres la signature du mandat par le client, Twikey prend en charge l'enregistrement aupres de la banque : des rappels sont envoyes si le mandat n'a pas encore ete active, et Twikey teste periodiquement si l'enregistrement a ete complete. Une fois l'enregistrement confirme, le mandat devient entierement signe et un evenement AcceptedBank est envoye via webhook. Si l'enregistrement n'est pas confirme apres les tentatives, le mandat reste non signe.

Le comportement de validation B2B est configure par profil dans le tableau de bord Twikey.

Feed de mandats

Une fois les mandats ou tokens crees, Twikey devient la source de verite pour tout ce qui leur arrive. Au lieu d'interroger les mandats individuellement, tous les changements sont disponibles via le feed de mandats. Ce feed de mandats est base sur les etats : il retourne le dernier etat de chaque mandat qui a change depuis la derniere lecture. Cela inclut les nouveaux mandats signes, les modifications (telles que les changements d'adresse ou d'IBAN) et les annulations. Pour chaque mise a jour de mandat, le feed fournit des details tels que les informations du signataire, la methode de signature utilisee, les raisons de modification et les raisons d'annulation. Il est attendu que le feed soit consomme jusqu'a ce qu'il ne reste plus de mises a jour, garantissant que tous les changements sont traites.

Par defaut, le feed de mandats retourne tous les attributs disponibles. Pour reduire la reponse aux seuls champs necessaires, des parametres include peuvent etre utilises. Les options disponibles sont : mandate, person, signature, plan, tracker, cancelled_mandate, paidamount et payment.

Chaque entree du feed correspond a l'un des trois types de messages :

• Mandat signe : le corps du message commence par Mndt, contenant les details complets du mandat.
• Modification : le corps du message commence par l'objet AmdmntRsn avec un champ Rsn decrivant la raison de la mise a jour.
• Annulation : le message commence par CxlRsn avec un champ Rsn decrivant la raison de l'annulation.

La colonne etat dans le tableau ci-dessous reflete les etats reels des mandats tels que retournes par le endpoint de details du mandat.

Etats intermediaires Contrairement au feed de paiements, qui est base sur les evenements et inclut tous les evenements intermediaires, le feed de mandats ne reflete que l'etat actuel. Si un mandat a traverse plusieurs changements d'etat entre deux lectures du feed, seul l'etat final est retourne. Pour capturer tous les etats intermediaires, le webhook (type=contract) peut etre utilise pour etre notifie immediatement lorsqu'une mise a jour se produit. En recuperant le feed immediatement apres avoir recu un webhook, chaque etat peut etre enregistre avant qu'il ne change a nouveau.

Types d'accords retournes Par defaut, le feed retourne les mandats CORE et B2B. Pour inclure d'autres types tels que les tokens de carte de credit, l'en-tete X-TYPES peut etre utilise pour specifier quels types inclure.

Actions sur un mandat

Une fois qu'un mandat ou token a ete cree, des actions supplementaires sont disponibles via le endpoint POST /creditor/mandate/{mndtId}/action. Ces actions se repartissent en trois categories.

Actions de communication Ces actions sont utilisees pour guider les mandats non signes vers leur completion.

• method = invite : renvoyer l'invitation de signature par email
• method = reminder : envoyer un rappel au client pour signer le mandat

Libre-service client Pour les mandats signes, le client peut avoir acces a la gestion de ses propres details de mandat.

• method = access : fournit un lien vers le portail client pour le mandat specifique. Via le portail, le client peut mettre a jour son IBAN, modifier les attributs modifiables et gerer les details de son mandat.

Surcharges de validation B2B Pour les mandats B2B, le comportement de validation configure sur le profil peut etre surcharge par mandat.

• method = automaticCheck : activer la validation automatique pour ce mandat specifique, surchargeant la valeur par defaut du profil
• method = manualCheck : desactiver la validation automatique pour ce mandat specifique, surchargeant la valeur par defaut du profil

Cycle de vie du mandat

Mise a jour des details du mandat Une fois un mandat signe, des details tels que l'adresse, l'IBAN, le numero de mobile, l'email, le nom de l'entreprise, la langue et tout attribut personnalise defini sur le template peuvent etre mis a jour via POST /creditor/mandate/update. Les mises a jour d'un mandat sont reflettees dans le feed de mandats.

Annulation des mandats Les mandats peuvent etre annules via DELETE /creditor/mandate. Meme lorsqu'une annulation est recue en dehors de Twikey, il est recommande de la communiquer afin que tous les systemes puissent rester synchronises.

Nettoyage automatique des mandats non signes Les mandats ou tokens non signes expirent automatiquement apres 12 mois, ou apres 6 mois une fois que le lien de signature a ete ouvert. Si un nouveau mandat est cree sur le meme profil pour le meme client et que le nouveau mandat est signe, tous les anciens mandats non signes pour ce client sont automatiquement supprimes, maintenant l'environnement propre de mandats et tokens non signes persistants.

Liens de paiement

Les liens de paiement sont destines aux paiements ponctuels sans mandat ni token et peuvent etre crees via POST /creditor/payment/link. La ou le endpoint de facture agit comme une implementation "envoyer et oublier" qui gere la selection de methode, le suivi, la conversion de mandat et la communication, les liens de paiement laissent ce controle a l'integration.

Les liens de paiement redirigent le client directement vers le PSP, contournant entierement la page de paiement Twikey. Si l'ecran de selection de methode de paiement cote PSP doit egalement etre ignore, cela peut etre fait en incluant le parametre method dans l'appel de creation. Cela fait des liens de paiement le bon choix lorsqu'un checkout personnalise, une page d'accueil ou un flux de communication existe deja et que l'orchestration automatique du endpoint de facture n'est pas necessaire.

Flux de paiement client

Independamment de la facon dont le lien de paiement est cree, il existe deux modeles pour livrer le lien de paiement au client.

Twikey envoie l'invitation Lorsqu'un email est fourni et que sendInvite est defini, Twikey livre le lien de paiement directement au client. Cela convient bien aux demandes de paiement autonomes ou aucune page d'accueil ou flux de communication supplementaire n'est necessaire.

Rediriger le client Au lieu de faire envoyer l'invitation par Twikey, l'URL du lien de paiement est retournee dans la reponse API et peut etre integree dans des flux personnalises, des communications ou des pages. C'est ideal pour les flux de checkout dans les sites web ou lorsque les communications sont gerees par un systeme externe.

Lier un lien de paiement a un paiement existant

Un lien de paiement peut etre lie a une ou plusieurs transactions impayees existantes en passant txref lors de la creation du lien. Une fois le lien de paiement regle, toutes les transactions liees sont marquees comme payees egalement. Cela est utile pour consolider plusieurs montants impayes en une seule action de paiement lors d'un suivi personnalise de transactions impayees.

Il est egalement possible de creer un lien de paiement sur une facture existante en fournissant le parametre invoice avec le numero de facture. Cela permet d'encaisser le paiement d'une facture existante directement via le PSP plutot que via la page de paiement Twikey hebergee utilisee par le endpoint de facture.

Feed de liens de paiement

Le feed de liens de paiement fonctionne sur le meme modele base sur les etats que le feed de mandats : chaque appel a GET /creditor/payment/link/feed retourne les entrees qui ont change depuis la derniere recuperation. Chaque entree represente l'etat actuel d'un lien de paiement, pas un evenement individuel.

Par defaut, seules les mises a jour payees sont retournees. Passer all=true inclut tous les changements d'etat. Des details supplementaires peuvent etre inclus en ajoutant des parametres include : customer, meta, time et refunds. Ceux-ci ne sont pas inclus par defaut pour garder la reponse compacte.

Validation des webhooks de liens de paiement

Pour les integrations de checkout, il est important de verifier qu'un webhook provient reellement de Twikey. La validation du webhook peut etre effectuee en validant l'en-tete x-signature. C'est le meme mecanisme de validation utilise pour tous les webhooks Twikey. Consulter la reference des webhooks pour les details complets.

Remboursement d'un lien de paiement

Un lien de paiement regle peut etre rembourse totalement ou partiellement via POST /creditor/payment/link/{id}/refund. La prise en charge du remboursement depend du PSP active dans le portail Twikey. L'etat du remboursement est reflete dans le feed de liens de paiement lorsque le parametre include approprie est egalement ajoute.

Transactions

Contrairement au flux de paiements ou les factures sont gerees et encaissees automatiquement, les transactions operent directement sur les mandats ou tokens. Une transaction est toujours creee sur un mandat specifique, pas sur un client. Pour cette raison, le mapping des transactions au bon mandat ou token est gere par l'integration, pas par Twikey.

Comme pour les mandats et les liens de paiement, travailler directement avec les transactions offre un controle plus fin sur le processus d'encaissement, mais implique egalement plus de responsabilite dans la gestion correcte du flux.

Les transactions sont creees via POST /creditor/transaction, en passant la reference du mandat, le montant et un message (affiche sur le releve bancaire du client). Twikey regroupe les transactions en attente en lots et les soumet a la banque ou au PSP pour traitement. Une fois le retour recu, un webhook type=payment est envoye et les resultats peuvent etre recuperes via le feed de transactions. Lorsqu'une transaction echoue, le processus de relance configure demarre automatiquement.

Feed de transactions

Le feed de transactions fonctionne sur le meme modele base sur les etats que le feed de mandats : chaque appel a GET /creditor/transaction retourne l'etat actuel de chaque transaction qui a change depuis la derniere recuperation. Chaque appel fait avancer la position, de sorte qu'il est attendu que le feed soit consomme jusqu'a ce qu'il soit vide. Pour enregistrer tous les etats intermediaires, le webhook de paiement (type=payment) peut etre utilise pour declencher une recuperation du feed des qu'un changement se produit.

Le flag final Chaque entree inclut egalement un flag final :

• final=true indique qu'aucune action automatique supplementaire ne sera effectuee sur cette transaction. Cela s'applique aux transactions payees et reglees, ou lorsque toutes les etapes de suivi automatique ont ete epuisees apres l'echec de la transaction.
• final=false indique que Twikey effectue encore un suivi automatique et que d'autres changements d'etat sont attendus.

Note : une transaction PAID + final=true peut toujours etre annulee par la banque ulterieurement (par exemple un remboursement ou une annulation). En pratique, une transaction de prelevement automatique reviendra presque toujours d'abord comme PAID + final=true, car c'est ainsi que les banques communiquent sur les prelevements automatiques : le lot entier est marque comme paye, et les jours suivants la banque communique sur les transactions individuelles non payees.

Suivi automatique Lorsqu'une transaction echoue, Twikey effectue des etapes de suivi automatique telles que la re-proposition du paiement, l'envoi de notifications au client et la proposition de methodes de paiement alternatives. Le feed reflete le resultat de ces etapes a mesure qu'elles se terminent. Une transaction peut passer de ERROR a PAID si une etape de suivi reussit, ou rester en ERROR avec final=true une fois que toutes les etapes ont ete epuisees.

Parametres d'inclusion Par defaut, le feed retourne une reponse compacte. Des details supplementaires peuvent etre recuperes en ajoutant des parametres include :

• collection - l'identifiant du lot d'encaissement
• lastupdate - horodatage du changement d'etat le plus recent
• action - toutes les actions de suivi automatique prises en cas de transaction echouee
• action_payment - comme action mais n'inclut que les actions prises depuis le dernier appel au feed
• link - un lien de paiement pour le client
• stage - l'etape actuelle de la transaction
• seq - le numero de sequence dans le feed

Transactions en lot

Au lieu de creer des transactions une par une, jusqu'a 5 000 transactions peuvent etre soumises en une seule requete via POST /creditor/transaction/bulk. Apres soumission, Twikey traite le lot de maniere asynchrone. Un webhook type=bulk est envoye une fois le traitement termine, et le statut du lot peut etre verifie en utilisant l'identifiant de lot retourne.

Remboursement d'une transaction

Un remboursement peut etre initie sur toute transaction payee via POST /creditor/transaction/{id}/refund. La facon dont le remboursement est traite depend de la maniere dont la transaction originale a ete encaissee.

Pour les transactions de prelevement automatique, le remboursement est ajoute a un fichier de virement. Ce fichier doit etre telecharge, charge a la banque et signe avant que le remboursement ne soit execute. Le montant est rembourse sur l'IBAN du mandat original par defaut.

Pour les transactions encaissees via un PSP, que ce soit par prelevement automatique via un PSP ou par carte de credit recurrente, Twikey transmet le remboursement directement au PSP pour traitement.

Plus de guides

Les guides suivants sont en cours de preparation :

• Abonnements
• Virements
• Reservations
• Identification client
• Verifications IBAN-nom
• Recouvrements

En attendant, la reference API couvre tous les endpoints disponibles.