PSP payment ( psp_payment )

Role

Every incoming payment handled through a PSP — whether from a Stripe webhook, a bank transfer detected through open banking, or a manual record — is represented as a psp_payment. It documents raw collection: how much was received, by which method, and which order or receivable it relates to.

The psp_payment then feeds reconciliation: once applied through reconcile_payment, it updates the settlement_status of the relevant invoices and triggers recalculation of the buyer's receivable for the buyer.

Identifier and structure

Every PSP payment has a stable identifier prefixed with 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"
}

Fields

Status

The status describes the lifecycle of the payment intent and then its collection state. A PSP payment normally starts in draft : Ormuz has defined the intent, but no provider payment has yet been established. pending instead means that the provider created or accepted the intent and collection is still awaited.

Status may be set at creation — useful when the PSP signal has already been processed — or updated through POST /v1/psp-payments/:id. A transition to a status other than pending emits the corresponding event.

Attachment basis

The field basis qualifies the commercial intent of the payment. It determines which linking fields are required or forbidden and provides reconciliation context.

Intent idempotency and provider reference

A nouveau psp_payment is first created as an Ormuz intent in status draft, without a provider reference. If a retry attempts to recreate the same draft before any external execution, Ormuz reuses the existing intent when its type, amount, currency, and business attachment key are identical.

source_reference is populated later, when the provider has actually created or identified its object. This reference is unique per merchant and written once; it then correlates provider updates and events to the same PSP payment. It does not replace draft deduplication before the external call.

Liaison payment

A psp_payment may be linked to a payment plateforme via payment_idobject. This link bridges raw PSP-side collection and the reconciled Ormuz-side payment.

Link constraints:

• The payment must belong to the same merchant and use the same currency.
• A PSP payment may be attached to only one payment; reassignment is blocked once linked.
• The PSP-payment amount must not exceed the capacity of the target payment.
• Setting payment_id to null unlinks the PSP payment.

PSP refunds

A PSP refund is also a persisted intent before the provider call. The node refund_psp_payment creates a psp_payment of type refund with status draft, linked through source_psp_payment_id to an already-successful source PSP payment. The PSP extension then materializes this refund and converges its status with the provider. The parent payment remains succeeded: its amount_refunded field aggregates successful child refunds; there is no parent status refunded.

For credit notes, create_credit_note_psp_refunds resolves the PSP payments that actually funded the relevant invoices, reserves remaining refundable capacity, and creates the corresponding intents. Creation may remain separate per credit note or be aggregated by source PSP payment according to process needs.

An active intent reserves its share of refundable capacity, so two concurrent processes cannot silently commit the same amount. Provider execution remains an explicit step, distinct from creating the Ormuz intent.

In processes

create_psp_payment

This helper creates or reuses an intent psp_payment draft from the supplied business basis. It does not request a provider source_reference reference at creation: that reference is attached later by the capability that actually executes or synchronizes the payment.

Main parameters

{
"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"
}

Output

{
"psp_payment": "platform.psp_payment"
}

reconcile_payment

Allocates a PSP payment or bank payment to one or more Ormuz receivables according to an allocation proposal. Updates document statuses and receivable according to the received source.

Parameters

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

Output

{
"payment_allocation": "platform.payment_allocation"
}

The receivable_allocation is typically produced by the node propose_payment_allocation which identifies candidate invoices for a given amount and company.

Nodes Stripe

Several Stripe integration nodes produce or consume a psp_payment :

Events

When the PSP payment is created directly with a status other than pending (ex. succeeded), both events psp_payment.created and psp_payment.succeeded are emitted at creation. Later status transitions emit only the event for the new status.