Paiement PSP (psp_payment)

Rôle

Chaque paiement entrant traité via un PSP — qu'il provienne d'un webhook Stripe, d'un virement bancaire détecté par open banking ou d'un enregistrement manuel — est représenté sous la forme d'un psp_payment. Il documente l'encaissement brut : combien a été reçu, via quelle méthode, et à quelle commande ou créance il se rapporte.

Le psp_payment alimente ensuite le rapprochement : une fois appliqué via reconcile_payment, il met à jour le settlement_status des factures concernées et déclenche le recalcul du receivable de l'acheteur.

Identifiant et structure

Chaque PSP payment porte un identifiant stable préfixé par psp_.

{
  "object": "psp_payment",
  "id": "psp_7e3b9f2a1c4d8e5f",
  "merchant_id": "mer_1a2b3c4d5e6f7a8b",
  "buyer_id": "cmp_3a8f1d9c2b4e7f6a",
  "checkout_session_id": null,
  "order_id": null,
  "invoice_id": "inv_4a7b2e9f1c3d8a5e",
  "payment_id": null,
  "basis": "invoice",
  "basis_snapshot_at": null,
  "basis_snapshot_amount": null,
  "source_reference": "pi_3Nx8kLInvalidExample",
  "metadata": {},
  "amount": 120000,
  "amount_received": 120000,
  "currency": "eur",
  "payment_method": "sepa_debit",
  "status": "succeeded",
  "created_at": "2026-06-17T12:00:00.000Z",
  "updated_at": "2026-06-17T12:05:00.000Z"
}

Champs

Statut

Le status décrit le cycle de vie de l'intention de paiement puis son état d'encaissement. Un PSP payment commence normalement en draft : Ormuz a défini l'intention, mais aucun paiement provider n'est encore établi.pending signifie au contraire que le provider a créé ou accepté cette intention et que l'encaissement reste attendu.

Le statut peut être fixé à la création (utile quand le signal PSP est déjà traité) ou mis à jour via POST /v1/psp-payments/:id. Une transition vers un statut différent de pending émet l'événement correspondant.

Base de rattachement

Le champ basis qualifie l'intention commerciale du paiement. Il détermine quels champs de liaison sont requis ou interdits, et fournit du contexte pour le rapprochement.

Idempotence de l’intention et référence provider

Un nouveau psp_payment est d’abord créé comme intention Ormuz au statut draft, sans référence provider. Si une reprise tente de recréer le même draft avant toute exécution externe, Ormuz réutilise l’intention existante lorsque son type, son montant, sa devise et sa clé métier de rattachement sont identiques.

source_reference est renseigné ensuite, lorsque le provider a réellement créé ou identifié son objet. Cette référence est unique par marchand et écrite une seule fois ; elle permet ensuite de corréler les mises à jour et événements provider au même PSP payment. Elle ne remplace pas la déduplication du draft avant l’appel externe.

Liaison payment

Un psp_payment peut être lié à un objet payment plateforme via payment_id. Ce lien établit le pont entre l'encaissement brut côté PSP et le paiement rapproché côté Ormuz.

Contraintes du lien :

• Le paiement doit appartenir au même marchand et avoir la même devise.
• Un PSP payment ne peut être rattaché qu'à un seul payment (réassignation bloquée une fois lié).
• Le montant du PSP payment ne doit pas dépasser la capacité du payment cible.
• Mettre payment_id à null délie le PSP payment.

Remboursements PSP

Un remboursement PSP est lui aussi une intention persistée avant l’appel provider. Le noderefund_psp_payment crée un psp_payment de type refund au statutdraft, lié par source_psp_payment_id à un paiement PSP source déjà réussi. L’extension PSP matérialise ensuite ce remboursement et fait converger son statut avec le provider. Le paiement parent reste succeeded : son champ amount_refunded agrège les remboursements enfants réussis, il n’existe pas de statut parent refunded.

Pour des avoirs, create_credit_note_psp_refunds résout les paiements PSP qui ont réellement financé les factures concernées, réserve la capacité encore remboursable et crée les intentions correspondantes. La création peut rester séparée par avoir ou être agrégée par paiement PSP source selon le besoin du processus.

Une intention active réserve sa part du montant remboursable : deux processus concurrents ne peuvent donc pas engager silencieusement le même montant. L’exécution provider reste une étape explicite, distincte de la création de l’intention Ormuz.

Dans les processus

create_psp_payment

Ce helper crée ou réutilise une intention psp_payment draft à partir de la base métier fournie. Il ne demande pas de source_reference provider à la création : cette référence est attachée plus tard par la capacité qui exécute ou synchronise réellement le paiement.

Paramètres principaux

{
  "company": "platform.company",
  "order": "platform.order",
  "invoice": "platform.invoice",
  "receivable": "platform.receivable",
  "checkout_session": "platform.checkout_session",
  "amount": 120000,
  "amount_received": 120000,
  "currency": "eur",
  "payment_method": "sepa_debit",
  "status": "succeeded",
  "source_reference": "pi_3Nx8kL"
}

Sortie

{
  "psp_payment": "platform.psp_payment"
}

reconcile_payment

Impute un PSP payment ou un payment bancaire sur une ou plusieurs créances Ormuz selon une proposition d'allocation. Met à jour les statuts des documents et le receivable selon la source reçue.

Paramètres

{
  "payment": "platform.payment | platform.psp_payment",
  "receivable_allocation": "common.receivable_allocation"
}

Sortie

{
  "payment_allocation": "platform.payment_allocation"
}

La receivable_allocation est typiquement produite par le node propose_payment_allocation qui identifie les factures candidates pour un montant et une company donnés.

Nodes Stripe

Plusieurs nodes d'intégration Stripe produisent ou consomment un psp_payment :

Événements

Si le PSP payment est créé directement avec un statut autre que pending (ex. succeeded), les deux événements psp_payment.created et psp_payment.succeeded sont émis à la création. Les transitions de statut ultérieures n'émettent que l'événement du nouveau statut.