Exposition crédit (credit_exposure)

Rôle

Là où le receivable agrège des factures existantes pour répondre à « combien me doit cet acheteur ? », la credit_exposure répond à « combien de crédit ai-je accordé à cet acheteur, et combien est encore ouvert ? »

L'exposition est un objet persisté — contrairement au receivable, elle n'est pas recalculée depuis les factures. Elle est construite explicitement par vos processus d'orchestration, mouvement après mouvement, à travers un journal immuable. Cela lui permet de couvrir des flux qui n'ont pas encore de facture émise (autorisation de crédit, financement d'une commande en cours) ou qui impliquent une entreprise financeur.

Il existe au plus une exposition par triplet (buyer_id, merchant_id, currency).

Identifiant et structure

Chaque exposition porte un identifiant stable préfixé par cex_. Chaque mouvement du journal porte le préfixe cem_.

{
  "object": "credit_exposure",
  "id": "cex_2b4d1f8a9c3e7f5b",
  "buyer_id": "cmp_3a8f1d9c2b4e7f6a",
  "merchant_id": "mer_1a2b3c4d5e6f7a8b",
  "currency": "eur",
  "status": "active",
  "authorized_amount_excluding_tax": 500000,
  "authorized_amount_including_tax": 600000,
  "consumed_amount_excluding_tax": 100000,
  "consumed_amount_including_tax": 120000,
  "released_amount_excluding_tax": 0,
  "released_amount_including_tax": 0,
  "settled_amount_excluding_tax": 83334,
  "settled_amount_including_tax": 100000,
  "cancelled_amount_excluding_tax": 0,
  "cancelled_amount_including_tax": 0,
  "expired_amount_excluding_tax": 0,
  "expired_amount_including_tax": 0,
  "outstanding_amount_excluding_tax": 416666,
  "outstanding_amount_including_tax": 500000,
  "movements": [
    {
      "id": "cem_1a2b3c4d5e6f7a8b",
      "type": "credit_granted",
      "amount_excluding_tax": 500000,
      "amount_including_tax": 600000,
      "source_type": "checkout_session",
      "source_id": "cs_5e2d8f1a9b3c4d7e",
      "created_at": "2026-06-17T10:00:00.000Z"
    },
    {
      "id": "cem_9f2e1a4b3c8d7e6f",
      "type": "credit_settled",
      "amount_excluding_tax": 83334,
      "amount_including_tax": 100000,
      "source_type": "payment",
      "source_id": "pay_4a7b2e9f1c3d8a5e",
      "created_at": "2026-06-18T09:15:00.000Z"
    }
  ],
  "metadata": {},
  "created_at": "2026-06-17T10:00:00.000Z",
  "updated_at": "2026-06-18T09:15:00.000Z"
}

Champs

Compteurs de montants

L'exposition accumule six paires de compteurs (HT + TTC). Chaque action sur l'exposition incrémente un compteur et peut réduire l'encours actif.

L'encours actif (outstanding_amount_*) est calculé en temps réel :

outstanding = max(0, authorized − released − settled − cancelled − expired)

Chaque compteur et le champ outstanding existent en deux bases (_excluding_tax et _including_tax). Lors d'une action, au moins une base doit être fournie.

Journal des mouvements

Le champ movements est un journal en ajout seul — chaque action sur l'exposition crée un mouvement immuable. C'est la trace complète de l'historique du crédit accordé à cet acheteur.

Statut

Interaction avec la limite de crédit

La limite de crédit définit le plafond autorisé ; l'exposition trace ce qui est effectivement engagé. Le crédit disponible est la différence entre les deux.

disponible = credit_limit.effective_amount − credit_exposure.outstanding_amount

Les nodes credit.evaluate_credit_availability et credit.check_credit_availability calculent automatiquement cette comparaison et produisent un objet credit_availability_check avec les champs suivants :

{
  "object": "credit_availability_check",
  "decision": "approved",
  "reason": "within_limit",
  "basis": "excluding_tax",
  "currency": "eur",
  "limit_amount": 500000,
  "used_amount": 416666,
  "requested_amount": 50000,
  "available_amount": 83334,
  "projected_used_amount": 466666,
  "projected_available_amount": 33334
}

Lorsque decision est rejected, la raison est insufficient_available_credit. Le processus route alors vers un chemin de refus ou de demande de garantie supplémentaire.

Dans les processus

L'exposition est entièrement pilotée par des nodes de processus — il n'y a pas de mise à jour automatique déclenchée par d'autres objets.

Flux typique : autorisation de crédit

Voici le schéma habituel d'un processus de décision crédit lors d'un checkout :

credit.evaluate_credit_availability (company, montant demandé)
  → approved → credit.grant_credit → créer checkout session / commande
  → rejected → notifier l'acheteur ou demander une garantie

Flux typique : clôture après paiement

payment.matched ou psp_payment.succeeded
  → credit.fetch_credit_exposure (company)
  → credit.settle_credit_exposure (montant encaissé)
  → [si outstanding = 0] credit.cancel_credit_exposure

Événements

Chaque action sur l'exposition émet un événement distinct. Le payload inclut l'état complet de l'exposition avant et après le mouvement (diff before/after), ainsi que le mouvement lui-même dans latest_movement.

L'événement credit_exposure.granted est émis à la fois à la création (première action grant) et lors de chaque augmentation ultérieure de l'encours autorisé.