Allocation de paiement (payment_allocation)

Rôle

Chaque fois qu'un paiement est rapproché d'une ou plusieurs factures, unepayment_allocation est créée pour matérialiser cette imputation. Elle répond à la question : quel montant de quel paiement a été appliqué sur quelle facture ?

L'allocation est un objet à deux niveaux :

• L'en-tête (pal_) identifie la source et son statut global d'imputation (partial ou complete).
• Les lignes (pai_) détaillent chaque imputation unitaire — quel montant a été appliqué sur quelle cible (facture, avoir, commande, etc.).

La création d'une allocation produit des effets de bord immédiats : mise à jour dusettlement_status des documents financiers concernés et mise à jour du status du paiement source. Le cycle de vie des factures reste indépendant.

Identifiant et structure

L'en-tête porte le préfixe pal_ ; chaque ligne porte le préfixe pai_.

{
  "object": "payment_allocation",
  "id": "pal_3c8f1a9b2d4e7f6a",
  "merchant_id": "mer_1a2b3c4d5e6f7a8b",
  "source_type": "psp_payment",
  "source_id": "psp_7e4b2d9f1c3a8e5f",
  "source_reference": null,
  "reverses_allocation_id": null,
  "reversed_by_allocation_id": null,
  "status": "complete",
  "created_at": "2026-06-17T14:30:00.000Z",
  "updated_at": "2026-06-17T14:30:00.000Z",
  "items": [
    {
      "object": "payment_allocation_item",
      "id": "pai_1a3f2b9c4d8e5f7a",
      "payment_allocation_id": "pal_3c8f1a9b2d4e7f6a",
      "target_type": "invoice",
      "target_id": "inv_4a7b2e9f1c3d8a5e",
      "amount": 120000,
      "currency": "eur",
      "created_at": "2026-06-17T14:30:00.000Z"
    }
  ]
}

Champs de l'en-tête

Lignes d'imputation

Chaque ligne (payment_allocation_item) décrit l'imputation d'un sous-montant de la source sur un document cible spécifique. Une allocation peut avoir plusieurs lignes si le paiement couvre plusieurs factures.

Les lignes sont accessibles via GET /v1/payment-allocations/:id (retourné dans l'objet parent) ou via le filtre GET /v1/payment-allocations?source_id=psp_….

Statut

Le statut de l'en-tête reflète si la totalité du montant source a été imputée.

Sources et cibles

Types de source

Types de cible

Effets de bord sur les cibles

La création d'une allocation met à jour immédiatement les statuts des objets concernés.

Création

Une payment_allocation se crée via POST /v1/payment-allocations. La requête décrit la source et la liste des lignes d'imputation.

POST /v1/payment-allocations

{
  "source_type": "psp_payment",
  "source_id": "psp_7e4b2d9f1c3a8e5f",
  "items": [
    {
      "target_type": "invoice",
      "target_id": "inv_4a7b2e9f1c3d8a5e",
      "amount": 120000,
      "currency": "eur"
    }
  ]
}

La plateforme valide que :

• La source est dans un statut éligible (voir tableau des sources).
• Toutes les cibles appartiennent au même marchand et ont la même devise que la source.
• Aucune cible n'est sur-imputée (total appliqué ≤ montant du document).
• La somme des lignes ne dépasse pas le montant source.
• Les cibles AR appartiennent au même acheteur que la source lorsque la source porte un buyer_id.

Les endpoints de lecture :

GET /v1/payment-allocations/:id
GET /v1/payment-allocations?source_type=psp_payment&source_id=psp_7e4b
GET /v1/payment-allocations?target_type=invoice&target_id=inv_4a7b

Dans les processus

En pratique, les payment_allocation ne sont pas créées manuellement — elles sont produites par les nodes de rapprochement.

Le flux habituel pour un encaissement PSP est :psp_payment.succeeded → propose_payment_allocation → reconcile_payment → payment_allocation créée → factures soldées.

Corriger une imputation

Une imputation est un fait immuable : elle ne se modifie pas et ne se supprime pas. Pour la corriger, on la contre-passe.

POST /v1/payment-allocations/:id/reverse

L'appel crée une allocation compensatoire — le miroir exact de l'allocation nommée, agrégé par cible, montants opposés. Aucune ventilation n'est choisie. Tous les statuts concernés se recalculent : paiement source, factures, avoirs, rollups de remboursement.

Corriger un montant se fait donc en deux temps : reverse puis une nouvelle allocation. Contre-passer libère la capacité de la source, si bien que réimputer est une opération ordinaire — il n'existe volontairement pas d'annulation d'annulation.

Refus

• une allocation déjà contre-passée ;
• une allocation compensatoire, qui ne peut pas l'être à son tour ;
• le miroir créé par POST /v1/payments/:id/reverse : il est imposé par le paiement qu'il contre-passe. Un prélèvement SEPA contesté et retourné à l'acheteur ne laisse rien à lettrer.

L'appel accepte un source_reference : un rejeu après timeout retourne la compensation existante au lieu d'en créer une seconde.

Identifier la contre-passation. Les montants négatifs ne suffisent pas à savoir quelle imputation est défaite lorsque plusieurs visent le même document. La relation est donc explicite, dans les deux sens :

{
  "id": "pal_compensation",
  "reverses_allocation_id": "pal_origine",
  "reversed_by_allocation_id": null
}

reverses_allocation_id est renseigné sur la compensation et pointe l'allocation défaite ; reversed_by_allocation_id est renseigné sur l'originale et pointe sa compensation. Les deux sont nuls sur une allocation ordinaire, et un connecteur n'a donc jamais à parcourir la liste pour savoir si une imputation a été défaite.

Documents annulés ou passés en perte. Contre-passer une imputation qui les visait fait redescendre leur règlement mais ne rouvre jamais le document : rouvrir un written_offmodifierait la créance en silence, sur une décision qui appartient au marchand. La plateforme émet invoice.terminal_settlement_changed et laisse un processus ou un opérateur reprendre la décision.

Événements

Les événements payment_allocation.partial et payment_allocation.complete sont mutuellement exclusifs — un seul est émis par création. Les événements sur les documents cibles (invoice.paid, invoice.partially_paid, payment.matched…) sont émis dans la même transaction.