Received payment ( payment )
A payment is Ormuz's record of an incoming payment from an accounting perspective. Where the psp_payment documents raw provider-side collection, the payment carries reconciliation status: was this amount applied to invoices, and by how much?
Role
The payment is the entry point for seller-side reconciliation. It may come from several channels — open banking, manual entry, or PSP payout — and follows its own reconciliation status independently from the collection status of an underlying psp_payment.
When a reconcilable payment is applied to one or more invoices through a
payment_allocation, it updates their settlement_status
(partially_paid or paid) and its own status changes to
matched or partially_matched. A payout
psp_with_allocations is the exception: it is not applied to documents.
Identifier and structure
Every payment has a stable identifier prefixed with 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"
}Fields
| Field | Type | Description |
|---|---|---|
id | string | Payment identifier (prefix `pay_`). |
object | string | Always "payment". |
merchant_id | string | Creditor merchant. |
buyer_id | string | null | Buyer company (`cmp_…`). May be absent on some aggregated receipts. |
type | enum | Movement nature: `payment`, `refund`, or `reversal`. |
source_payment_id | string | null | Parent payment for a related refund or reversal. |
amount_refunded | integer | Amount already refunded on a payment. |
amount_refundable | integer | Remaining refundable amount, calculated by the platform. |
reason | string | null | Reason for a refund, reversal, or explicit marking when relevant. |
source_reference | string | null | Reference in the source system (for example bank-transfer reference). |
metadata | object | Flat map of `string | number | boolean` scalars, following the API metadata convention. |
amount | integer | Total payment amount in cents (≥ 0). |
currency | string | ISO 4217 currency code in lowercase (for example `eur`). |
source | enum | Input channel for the data: `open_banking`, `manual`, `psp`, `psp_with_allocations`. |
payment_method | string | null | Payment method used, distinct from the source through which it entered Ormuz. |
status | enum | Intent or reconciliation state: `draft`, `pending`, `matched`, `partially_matched`, `unmatched`, `reversed`, `failed`, or `cancelled`. |
payment_date | date | Business date of the payment, distinct from `created_at`, which is the recording date. |
value_date | date | null | Bank value date. This is authoritative for reconciliation. |
reference | string | null | Transfer remittance information, 140 characters (ISO 20022 RmtInf/Ustrd). Free text passed without alteration. |
end_to_end_reference | string | null | Transaction reference, 35 characters (ISO 20022 PmtId/EndToEndId). Identifier assigned by the ordering party. |
import_batch_reference | string | null | Import-batch reference when no ImportBatch resource exists. |
created_at | datetime | Date recorded in the platform. |
updated_at | datetime | Last update date. |
Source
The source qualifies the payment origin and determines constraints on buyer_id and linked PSP payments.
| source | buyer_id | psp_payment_ids | Description |
|---|---|---|---|
open_banking | Required | — | Payment detected through an open-banking integration (bank statement). Buyer is known. |
manual | Required | — | Payment entered manually by an operator. Buyer is known. |
psp | Interdit | — | Aggregated PSP payout without buyer breakdown. No linked PSP payment. |
psp_with_allocations | Interdit | Required | PSP payout with the list of individually reconciled PSP payments. The payout is never applied to invoices: their `settlement_status` is already driven by PSP-payment allocations. |
Remittance information and transaction reference
reference and end_to_end_reference are not interchangeable: they are two distinct fields from the
ISO 20022standard that a SEPA transfer carries side by side.
reference | end_to_end_reference | |
|---|---|---|
| ISO 20022 field | RmtInf/Ustrd | PmtId/EndToEndId |
| Taille | 140 characters | 35 characters |
| Nature | free text passed to the beneficiary without alteration | identifier returned in reporting to both companies |
| Common name | remittance, label, communication | transaction reference |
On an incomingpayment, the payer fills both. Its transaction reference is theirs, often unusable, and frequently has the literal value NOTPROVIDED — the connector then normalizes it to null. It is therefore the remittance text field that carries the invoice number and is used for reconciliation.
On an outgoing (supplier_paymentpayment, Ormuz is the ordering party: it assigns the transaction reference, which defaults to the
public_id . The bank transports and returns it on the statement, making it the debit-reconciliation key.
end_to_end_reference is nullable and has no uniqueness constraint, deliberately: a unique index would collide on all receipts lacking a reference. It is not an idempotency key either — that goes through extension_object_mappings and a connector-specific fallback key.
The standard provides a third reference, the structured reference of the beneficiary (RmtInf/Strd/CdtrRefInf, ISO 11649 “RF”, and national equivalents: Belgian structured communication, Norwegian KID, Finnish viitenumero). Defined by the creditor on the invoice and copied by the payer, it is the most reliable reconciliation key where used. Ormuz does not issue one: reminders operate on the receivable rather than the invoice.
Reconciliation status
The status carries two phases depending on movement nature. A received payment normally starts in pending then evolves through reconciliation. A refund intent starts in draft and may become pending when a bank movement materializes it, or end in failed/cancelled before execution. Reconciliation statuses are updated in the same transaction as the corresponding applications.
| Status | Description |
|---|---|
draft | Refund intent created before the bank movement is materialized. |
pending | Movement materialized and available for reconciliation, or received payment not yet fully allocated. |
matched | Fully allocated — total applications equal the movement amount. |
partially_matched | Partially allocated — a residual balance remains open. |
unmatched | Incoming payment explicitly marked as not reconcilable. |
reversed | Original payment reversed by a distinct `reversal` movement. |
failed | Refund intent that could not be materialized through the banking channel. |
cancelled | Refund intent canceled before materialization. |
The event reflects the status reached after application:
payment.matched when the amount is fully reconciled, or
payment.partially_matched when a balance remains to allocate.
Linked PSP payments
For source psp_with_allocations, a list of
psp_payments is provided at creation through psp_payment_ids. These PSP payments must all be in status succeeded, belong to the same merchant and currency, and not already be linked to another 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"
]
}The total amount of linked PSP payments must fall within ±5% of the payment amount to absorb PSP processing fees. PSP payments are retrievable through
GET /v1/payments/:id/psp-payments.
For psp_with_allocations, each psp_payment already carries its allocation to invoices and updates their settlement_status. The aggregated payout therefore creates no second payment_allocation and modifies no document; its status derives from its components.
Application to invoices
Applying a payment to invoices creates a payment_allocation
describing how the amount is distributed. Application is atomic and updates invoice statuses in the same transaction.
Effect on settlement_status
Each invoice touched by an application of type payment has its
settlement_status progresses without changing its lifecycle status status:
| Applied amount vs. amount including tax | Resulting settlement_status |
|---|---|
| Total applications = invoice amount including tax | paid |
| Total applications < amount including tax | partially_paid |
The same settlement axis is used regardless of receipt origin. There is no longer a separate buyer-side and seller-side settlement status.
Application constraints
- Only payments in status
pendingorpartially_matchedmay be applied. - The cumulative total of applications cannot exceed the payment amount.
- Target invoices must belong to the same merchant and use the same currency.
- For non-PSP sources with a
buyer_id, invoices must belong to the same buyer.
Refunds
A bank or open-banking refund is represented by a payment of type refund
linked to its source payment. It starts in draft: Ormuz has reserved a refund intent, but no bank movement is yet considered executed.
This separation avoids confusing a process decision with the final financial fact. Refundable capacity on the source payment accounts for already-executed refunds and active intents so a concurrent process cannot reserve the same capacity twice.
Core nodes refund_payment and create_credit_note_payment_refunds create these intents. The second starts from issued credit notes, finds the payments that actually funded the relevant invoices, and can produce one refund per credit note or aggregate by source payment.
PSP refunds follow the same intent principle draft, but are carried by
psp_payment and executed by the corresponding PSP extension.
In processes
reconcile_payment
This helper applies a payment or a psp_payment to receivables according to an allocation proposal. It uses the type of the received object as the source of the payment_allocation. Payments with source
psp_with_allocations are PSP payouts and do not go through this node: their status derives from the PSP payments they group.
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
propose_payment_allocation.
An aggregated PSP payout (psp_with_allocations) is not reconciled: it carries no buyer information, and the invoices were already settled by the psp_payment payments it pays out. Its status derives from its components — matched when each of them is allocated.
fetch_payment
Generic helper to retrieve a payment by identifier in an orchestration process.
Events
| Event | Trigger |
|---|---|
payment.received | The payment was just created. |
payment.matched | The payment is fully reconciled to its targets. |
payment.partially_matched | The payment is partially reconciled and retains a residual balance. |
payment.unmatched | The payment was marked `unmatched`. |
payment.reversed | The payment was reversed. |
payment_refund.created | A customer-refund intent is created in `draft`. |
payment_refund.executed | The customer refund is materialized through the banking channel. |
payment_refund.failed | The banking channel refuses to materialize the customer refund. |
payment_refund.cancelled | The customer-refund intent is canceled before materialization. |
payment_refund.matched | The customer refund is fully reconciled to its targets. |