Supplier payment ( supplier_payment )
Represents a supplier disbursement driven by Ormuz or an inverse movement attached to that disbursement, without conflating the instruction created by the process with execution actually observed on the payment rail.
Role
supplier_payment belongs to the Accounts Payable context: it describes movement between merchant and supplier. It is distinct from payment, which represents customer-side incoming cash, and psp_payment, which carries PSP-side execution for receipts.
The type field is payment for a supplier disbursement and refund for the inverse movement received from a supplier. The amount is always positive; direction is carried by type and relationship to the original movement.
Instruction and execution are two different facts
Ormuz may create the instruction in `pending` or `scheduled`. `executed` or `failed` corresponds to the payment-rail result; `cancelled` remains an explicit ending before successful execution.
Creating the object expresses disbursement intent. For a type=payment, the API allows creation only in
pending or scheduled. Transitioning to executed or failed status; transition occurs later when execution becomes known.
A process must not directly create a supplier payment as executed to mean “to be paid”. Use the instruction state, then let the payment integration or authorized operation establish actual execution.
Lifecycle
| Status | Meaning | Typical next step |
|---|---|---|
pending | Instruction created, not yet scheduled or executed. | Checks, approval, submission to the payment rail. |
scheduled | Execution planned for a future date or window. | Wait for execution or cancel while it remains cancelable. |
executed | The disbursement is considered executed. | Create AP allocations and reconcile the movement with the relevant documents. |
failed | Execution did not succeed. | Handle the incident, correct the cause, and possibly create a new instruction. |
cancelled | The instruction was canceled before normal completion. | Do not continue steps assuming cash actually left. |
The payment_date is the planned business date; value_date is populated when the execution value date is known.
provider_reference retains the reference assigned by the external rail.
Inverse supplier movements
A supplier_payment with type=refund represents returned funds linked to an original supplier payment. It must reference that movement through source_supplier_payment_id. The refund is created as executedbecause this type represents an inverse movement already observed rather than a new instruction to execute.
Ormuz tracks cumulative refunded amount on the parent payment and prevents executed refunds from exceeding the original amount. This preserves an explicit relationship between cash sent and later returned funds.
Key fields
| Field | Role |
|---|---|
supplier_id | Supplier receiving the disbursement. |
type | payment or refund; carries the economic direction of the movement. |
source_supplier_payment_id | Original supplier payment for an inverse movement. |
amount | Positive amount in the currency's minor unit. |
payment_method | transfer, direct_debit, card or manual. |
reference | Human-readable business payment reference. |
end_to_end_reference | End-to-end reference transmitted on rails that support it. |
source_reference | Stable identity in the source system, used for correlation/idempotency. |
API and process
The Core node create_supplier_payment creates a supplier-payment instruction from a process. Payment extensions can then materialize or observe execution according to their capabilities.
POST /v1/supplier-payments
{
"merchant_id": "mer_0123456789abcdef0123456789abcdef",
"type": "payment",
"supplier_id": "cmp_0123456789abcdef0123456789abcdef",
"amount": 125000,
"currency": "EUR",
"payment_method": "transfer",
"status": "scheduled",
"payment_date": "2026-09-30",
"reference": "Supplier invoice SINV-2048"
}GET /v1/supplier-payments/{id}
GET /v1/supplier-payments?supplier_id=cmp_...&status=scheduled
POST /v1/supplier-payments/{id}/execute
POST /v1/supplier-payments/{id}/fail
POST /v1/supplier-payments/{id}/cancel
POST /v1/supplier-payments/{id}/refundEvents
Important transitions are observable as platform events:
supplier_payment.createdsupplier_payment.scheduledsupplier_payment.executedsupplier_payment.failedsupplier_payment.cancelled
When execution must reduce supplier debt, use a payment_allocation with source_type=supplier_payment so reconciliation remains explicit and reversible.