Réconciliation de paiement

Rapprochez les paiements reçus — bancaires ou PSP — avec les créances ouvertes de la plateforme. Ce guide couvre la proposition d'allocation et la création d'unepayment_application exploitable par votre système financier.

Objectif métier

Quand un acheteur règle une créance, l'encaissement est représenté soit par un psp_payment lorsqu'il est observé chez un PSP, soit par un payment lorsqu'il est reçu directement, par exemple via open banking. Dans les deux cas, le processus doit déterminer quelles créances ce paiement couvre.

La réconciliation répond à deux questions : quelles créances ce paiement éteint-il ? et quelle partie du montant reste non imputée ? Le résultat est une payment_application, qui matérialise le fait d'imputation et fait évoluer les statuts des documents concernés.

Périmètre de ce guide Ce guide couvre la réconciliation côté acheteur pour les sources payment et psp_payment. Un payout PSP agrégé psp_with_allocations n'est jamais rapproché de documents : ses transactions PSP unitaires portent les allocations.

Objets impliqués

Objet	Rôle dans la réconciliation
`psp_payment`	Encaissement acheteur observé chez un PSP. Il peut être directement appliqué aux créances lorsqu'il est succeeded.
`payment`	Encaissement acheteur reçu hors PSP, par exemple par virement bancaire. Les payouts PSP agrégés ne sont jamais appliqués aux documents.
`receivable_allocation`	Proposition de distribution d'un montant sur des créances ouvertes. Objet transient produit par propose_payment_allocation.
`payment_application`	Fait persisté d'imputation. Lie une source payment ou psp_payment aux invoices, credit notes ou autres cibles retenues.

La receivable_allocation est un objet de type commun — elle n'est pas stockée directement, mais sert d'entrée typée au node reconcile_payment. Elle porte la liste des créances ciblées et les montants imputés sur chacune.

Parcours de réconciliation

Paiement reçu

Proposer l'allocation

Exact / sous-paiement

Excédent / ambigu / non apparié

Allouer et réconcilier

Un paiement reçu déclenche la proposition d'allocation. Selon le matching, le processus crée l'application ou route vers un traitement spécifique.

Réception du paiement

Un encaissement confirmé arrive comme psp_payment via un PSP ou comme payment via un canal direct. Le processus peut être déclenché par l'événement correspondant ou recevoir l'objet depuis une étape précédente.

Proposer l'allocation

Le node propose_payment_allocation recherche les factures ouvertes de la party dans une fenêtre temporelle configurable et propose la meilleure combinaison. Il route selon le résultat du matching.

Allouer et réconcilier

Sur les routes acceptées, reconcile_payment reçoit le payment ou psp_payment et la proposition retenue, puis crée la payment_application avec le type de source correspondant.

Proposer l'allocation

Le node propose_payment_allocation est un routeur. Il reçoit la party, le montant et la devise, cherche les créances ouvertes dans la fenêtre configurée et retourne la meilleure allocation candidate.

Paramètres clés

Paramètre	Rôle
`party`	Party dont les créances ouvertes sont recherchées.
`amount`	Montant reçu, exprimé dans l'unité mineure de la devise.
`currency`	Devise du paiement. Seules les créances dans la même devise sont considérées.
`invoice`	Optionnel. Restreint la recherche à une facture précise.
`reference`	Optionnel. Référence source de la facture pour affiner le matching.
`invoice_window_past_days`	Fenêtre de recherche dans le passé (défaut : 180 jours).
`invoice_window_future_days`	Fenêtre de recherche dans le futur (défaut : 30 jours).

Routes et actions recommandées

Route	Signification	Action recommandée
`exact_match`	Le montant reçu couvre exactement une combinaison de créances.	Allouer et réconcilier directement.
`underpayment`	Le montant est inférieur au total des créances proposées.	Allouer partiellement ; la créance reste ouverte pour le solde.
`overpayment`	Le montant dépasse le total des créances trouvées.	Décider du traitement de l'excédent — remboursement, avoir ou avoir en attente.
`ambiguous`	Plusieurs combinaisons de créances sont possibles sans critère discriminant.	Demander une résolution manuelle ou appliquer une règle métier déterministe.
`unmatched`	Aucune créance ouverte trouvée pour la party et le montant.	Signaler à l'équipe opérationnelle ou créer une créance ad hoc.

Routes non gérées Toutes les routes doivent être câblées dans le processus, même si certaines mènent à une alerte ou un log. Un paiement non rapproché tombé dans un chemin non connecté resterait silencieusement sans suite.

Allouer et réconcilier

reconcile_payment

Le node reçoit une source platform.payment ou platform.psp_payment et la receivable_allocation retenue. Il crée une payment_application dont le source_type est dérivé directement du type de la source.

Une seule primitive de rapprochement Le canal d'encaissement ne change pas l'action métier : dans les deux cas, Ormuz applique un montant reçu à des créances. Les contrôles propres à chaque source restent appliqués lors de la création de la payment_application.

Statuts et résultats

Statuts du psp_payment

`status`	Signification
`pending`	Paiement créé, fonds non encore confirmés.
`partially_funded`	Montant partiel reçu (0 < amount_received < amount).
`succeeded`	Fonds confirmés et disponibles pour la réconciliation.

Un psp_payment doit être succeeded avant application. Pour un payment, l'API vérifie qu'il est encore dans un état permettant une imputation et qu'il ne s'agit pas d'un payout psp_with_allocations.

Statuts de la payment_application

`status`	Signification
`partial`	La source n'est pas entièrement imputée ; une partie du montant reste disponible.
`complete`	La source est entièrement imputée par cette application et les applications précédentes.

Une payment_application partial n'est pas une erreur : elle signifie simplement qu'une partie de la source reste disponible après cette imputation.

Événements et suivi

Événement	Utilisation
`psp_payment.succeeded`	Déclencher un processus lorsqu'un encaissement PSP est confirmé.
`payment.received`	Déclencher un processus lorsqu'un encaissement hors PSP est enregistré.
`payment_application.complete`	L'imputation de la source est complète ; exporter le résultat vers le système financier si nécessaire.
`payment_application.partial`	Une partie de la source reste non imputée et peut nécessiter un traitement complémentaire.
`invoice.paid`	Une facture est entièrement réglée suite à l'imputation.
`invoice.partially_paid`	Une facture est partiellement réglée ; le solde reste dû.

Les événements payment_application.complete et payment_application.partial exposent le résultat de l'imputation. Les événements des documents concernés permettent en parallèle de suivre leur évolution.

Checklist d'intégration

Configurer le déclencheur adapté au canal : psp_payment.succeeded pour un PSP ou payment.received pour un encaissement direct.
S'assurer que la party associée à la source possède des créances ouvertes avant la proposition d'allocation.
Câbler toutes les routes de propose_payment_allocation — exact_match, underpayment, overpayment, ambiguous, unmatched.
Traiter explicitement les routes ambiguous et unmatched — alerte opérationnelle, règle déterministe ou résolution manuelle.
Passer la source payment ou psp_payment et la allocation_proposal retenue au node reconcile_payment.
Consommer payment_application.complete et payment_application.partial de façon idempotente.
Sur une application partial, décider explicitement du traitement du montant source encore disponible.
Relire la payment_application depuis l'API avant toute mise à jour comptable si votre intégration a besoin du détail complet des lignes.

← PrécédentGestion du crédit acheteur Suivant →Prélèvement SEPA