Paiement reçu (payment)

Rôle

Le payment est le point d'entrée du rapprochement côté vendeur. Il peut provenir de plusieurs canaux — open banking, saisie manuelle, ou reversement PSP — et suit son propre statut de rapprochement indépendamment du statut d'encaissement du psp_payment sous-jacent.

Lorsqu'un payment réconciliable est appliqué sur une ou plusieurs factures via une payment_allocation, il met à jour leur settlement_status(partially_paid ou paid) et son propre statut passe à matched ou partially_matched. Un payout psp_with_allocations constitue l'exception : il n'est pas appliqué aux documents.

Identifiant et structure

Chaque payment porte un identifiant stable préfixé par pay_.

{
  "object": "payment",
  "id": "pay_2c4f8a1e9b3d7f6e",
  "merchant_id": "mer_1a2b3c4d5e6f7a8b",
  "buyer_id": "cmp_3a8f1d9c2b4e7f6a",
  "type": "payment",
  "source_payment_id": null,
  "amount_refunded": 0,
  "amount_refundable": 120000,
  "reason": null,
  "source_reference": "VIR-2026-06-17-00042",
  "metadata": {},
  "amount": 120000,
  "currency": "eur",
  "source": "open_banking",
  "payment_method": "bank_transfer",
  "status": "matched",
  "payment_date": "2026-06-17",
  "reference": "VIREMENT ACHETEUR REF 00042",
  "import_batch_reference": null,
  "created_at": "2026-06-17T14:00:00.000Z",
  "updated_at": "2026-06-17T14:05:00.000Z"
}

Champs

Source

La source qualifie l'origine du paiement et détermine les contraintes sur buyer_id et les psp_payments liés.

Motif et référence d'opération

reference et end_to_end_reference ne sont pas interchangeables : ce sont deux champs distincts de la norme ISO 20022, que le virement SEPA transporte côte à côte.

Sur un encaissement, c'est le payeur qui remplit les deux. Sa référence d'opération est la sienne, souvent inexploitable, et vaut fréquemment la valeur littérale NOTPROVIDED — le connecteur la normalise alors en null. C'est donc le motif qui porte le numéro de facture et sert au rapprochement.

Sur un décaissement (supplier_payment), Ormuz est donneur d'ordre : il assigne la référence d'opération, qui vaut le public_id par défaut. La banque la transporte et la restitue sur le relevé, ce qui en fait la clé de rapprochement du débit.

end_to_end_reference est nullable et sans contrainte d'unicité, délibérément : un index unique ferait collisionner tous les encaissements dépourvus de référence. Ce n'est pas non plus une clé d'idempotence — celle-ci passe par extension_object_mappings et une clé de repli propre à chaque connecteur.

La norme prévoit une troisième référence, la référence structurée du bénéficiaire (RmtInf/Strd/CdtrRefInf, ISO 11649 « RF », et ses équivalents nationaux : communication structurée belge, KID norvégien, viitenumero finlandais). Définie par le créancier sur sa facture et recopiée par le payeur, c'est la clé de rapprochement la plus fiable là où elle est en usage. Ormuz n'en émet pas : la relance porte sur le receivable et non sur la facture.

Statut de rapprochement

Le status porte deux phases selon la nature du mouvement. Un encaissement reçu commence normalement en pending puis évolue avec son rapprochement. Une intention de remboursement commence en draft et peut devenir pending lorsqu’un mouvement bancaire la matérialise, ou terminer en failed/cancelled avant exécution. Les statuts de rapprochement sont mis à jour dans la même transaction que les applications correspondantes.

L'événement reflète le statut obtenu après l'application : payment.matched lorsque le montant est entièrement rapproché, ou payment.partially_matched lorsqu'un solde reste à affecter.

PSP payments liés

Pour la source psp_with_allocations, une liste de psp_payments est fournie à la création via psp_payment_ids. Ces psp_payments doivent tous être en statut succeeded, appartenir au même marchand et à la même devise, et ne pas être déjà liés à un autre payment.

POST /v1/payments

{
  "merchant_id": "mer_1a2b3c",
  "amount": 360000,
  "currency": "eur",
  "source": "psp_with_allocations",
  "payment_date": "2026-06-17",
  "psp_payment_ids": [
    "psp_7e3b9f",
    "psp_4a1c8d",
    "psp_9f2e6b"
  ]
}

Le total des montants des psp_payments liés doit être compris dans une tolérance de ±5 % du montant du payment (pour absorber les frais de traitement PSP). Les psp_payments sont récupérables via GET /v1/payments/:id/psp-payments.

Application sur les factures

Appliquer un payment sur des factures crée une payment_allocationqui décrit comment le montant est réparti. L'application est atomique et met à jour les statuts des factures dans la même transaction.

Effet sur le settlement_status

Chaque facture touchée par une application de type payment voit son settlement_status progresser, sans modifier son status de cycle de vie :

Le même axe de règlement est utilisé quelle que soit l'origine de l'encaissement. Il n'existe plus de statut de règlement distinct côté acheteur et côté vendeur.

Contraintes d'application

• Seuls les payments en statut pending ou partially_matched peuvent être appliqués.
• Le total cumulé des applications ne peut pas dépasser le montant du payment.
• Les factures cibles doivent appartenir au même marchand et avoir la même devise.
• Pour les sources non-PSP avec un buyer_id, les factures doivent appartenir au même buyer.

Remboursements

Un remboursement bancaire ou open-banking est représenté par un payment de type refundlié à son paiement source. Il commence en draft : Ormuz a réservé une intention de remboursement, mais aucun mouvement bancaire n’est encore considéré comme exécuté.

Cette séparation évite de confondre une décision du processus avec le fait financier final. Le montant remboursable du paiement source tient compte des remboursements déjà exécutés et des intentions actives afin qu’un processus concurrent ne puisse pas réserver deux fois la même capacité.

Les nodes Core refund_payment et create_credit_note_payment_refunds créent ces intentions. Le second part d’avoirs émis, retrouve les paiements réellement utilisés pour financer les factures concernées et peut produire un remboursement par avoir ou agréger par paiement source.

Les remboursements PSP suivent le même principe d’intention draft, mais sont portés parpsp_payment et exécutés par l’extension PSP correspondante.

Dans les processus

reconcile_payment

Ce helper applique un payment ou un psp_payment sur des créances selon une proposition d'allocation. Il utilise le type de l'objet reçu comme source de la payment_allocation. Les payments psp_with_allocations ne passent pas par ce node : leur statut est dérivé des psp_payments qu'ils regroupent.

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 propose_payment_allocation.

Un reversement PSP agrégé (psp_with_allocations) ne se rapproche pas : il ne porte aucune information acheteur, et les factures ont déjà été soldées par les psp_payment qu'il reverse. Son statut est dérivé de ses composants — matched lorsque chacun d'eux est alloué.

fetch_payment

Helper générique pour récupérer un payment par identifiant dans un processus d'orchestration.

Événements