Core business-model principles
The Ormuz model represents the actors, documents, decisions, and financial movements required to orchestrate a B2B journey. Its public objects remain independent from the providers and technical systems that feed the platform.
A model oriented around business outcomes
Each object answers a precise business question. A company represents a company; a
checkout_session carries a checkout attempt; a psp_payment describes a buyer-side payment; a payment represents a cash receipt observed by the merchant; a
payment_allocation explains how that movement is allocated to business documents.
This separation avoids giving several meanings to the same object. It also allows changing provider or source system without changing process business logic.
Model business reality and produced guarantees, not the structure of the external tool supplying data.
When does a concept deserve an object?
A concept generally becomes a public object when it has an identity, lifecycle, relationships, events, or direct usefulness in processes. Purely descriptive information remains a field of the object carrying it.
| Criterion | Example |
|---|---|
| The process must manipulate the concept directly | onboarding_case, invoice |
| The platform evolves its state | checkout_session, dispute |
| The concept produces business events | psp_payment, payment |
| It carries a durable relationship or evidence | contact_role, compliance_check |
| It results from a reusable calculation | receivable, credit_exposure |
Conversely, an address, currency, order reference, or amount does not become an independent object without its own business need. These remain structured or scalar properties.
An identifier and explicit type
Persisted resources expose a id prefixed identifier and an objectfield. The prefix aids readability and prevents mixing identifiers of different types, for example
cmp_* for a company, inv_* for an invoice, or cs_* for a checkout session.
| Champ | Garantie |
|---|---|
id | Stable identifier to retain in integrations. |
object | Functional type of the returned resource. |
merchant_id | Merchant scope to which the object belongs. |
created_at, updated_at | Time markers exposed when the object contract provides them. |
Relationship fields such as company_id, invoice_id or checkout_session_id
contain identifiers of linked objects.
Merchant scope and source of truth
A business object belongs to a merchant. Relationships between objects must stay within that scope unless a public contract explicitly says otherwise. This rule prevents a process or integration from accidentally linking data from different merchants.
Authority is not decided once for the whole object. It may vary by field and lifecycle phase. For example, an invoice may carry a reference and amounts controlled by the accounting system once issued while retaining a settlement_status calculated by Ormuz from payments and allocations.
When an external system tries to synchronize a field for which Ormuz is the source of truth, it cannot silently overwrite it. If values diverge, the operation fails so the process handles the conflict explicitly. Conversely, a field for which the external role is authoritative is updated from that source.
| Reference | Usage |
|---|---|
id Ormuz | Identify and link the resource across Ormuz APIs, events, and processes. |
source_reference | Retain the business identifier from the system of record, for example an ERP, CRM, or e-commerce ID. |
| Provider reference | Identify the object in a technical external service without replacing the business reference. |
A Stripe, ERP, or CRM identifier does not replace the Ormuz ID. Likewise, a technical provider identifier must not be placed in source_reference when that provider is not the business source of truth for the object.
Two systems may carry different views of the same subject without needing to merge them. For example, operational settlement of an invoice may be paid in Ormuz while the ERP has not reflected it yet. Each value remains true on its own authority plane.
Explicit relationships and usable objects
Important relationships are carried by explicit public fields. An invoice may reference its company; a PSP payment may reference a checkout session; an order may be linked to the invoices it produced.
In API requests, these relationships are generally expressed with IDs. In a process, a node declaring that it produces a company, an invoice, or a contact
must return a complete, directly reusable object, not a simple envelope containing its ID.
| Forme | Utilisation |
|---|---|
company_id: "cmp_*" | Create, filter, or link a resource through the API. |
company: platform.company | Pass a typed object between nodes. |
| Dedicated relationship | Carry its own semantics, for example a contact's role within a company. |
A rich business relationship must not be reduced to a free-form field. For example,
contact_role carries the role type, certification level, validity, and any powers.
Statuses describe a precise lifecycle
A status must answer one functional question. When an object carries several dimensions, they are separated. A checkout session, for example, distinguishes the end of the journey with
status from the financial outcome with payment_status.
Important transitions produce business events. A canonical event asserts that a state genuinely exists in Ormuz: invoice.issued, checkout_session.completed, or
onboarding_case.rejected. A signal received from a provider first describes what happened at that provider and does not automatically amount to mutation of an Ormuz object.
Use the event name, object, and payload to understand the produced guarantee. Do not infer a business change from a simple external signal until the process has established it.
A draft prepares creation; it is not yet a resource
A draft is a proposal to create a platform object. It follows the target object's contract but has no ID. It may come from a form, import, calculation, or adaptation of a provider object.
{
"id": "cmp_abc123",
"object": "company",
"merchant_id": "mer_abc123",
"legal_name": "ACME France SAS",
"trade_name": "ACME France",
"display_name": "ACME France",
"registration_number": "123456789",
"registration_country": "FR",
"source_reference": "CRM-1042"
}{
"object": "company",
"legal_name": "ACME France SAS",
"registration_number": "123456789",
"registration_country": "FR",
"is_buyer": true,
"is_supplier": false,
"source_reference": "CRM-1042"
}| Objet persistant | Creation draft |
|---|---|
| Has an ID. | Has no ID. |
| Can be referenced durably. | Remains a proposal until submitted. |
| Follows its lifecycle and produces its events. | Follows the target create contract as closely as possible. |
| Can be updated by operations defined by its contract. | Is reserved for creation, not modification of an existing object. |
When a draft comes from a provider, it may carry _source provenance linking the proposal to the provider, its object, and originating event. Business data remains in business fields of the draft.
Modeling guarantees
- Use identifiers supplied by Ormuz to reference objects in integrations.
- Give each object a clearly bounded business responsibility.
- Define the source of truth for each piece of data shared across systems.
- Retain external business references without confusing them with provider IDs.
- Express structural relationships through explicit typed fields or objects.
- Return complete objects when a node promises a platform object as output.
- Separate status axes when they answer different questions.
- Have canonical events produced by a business mutation that has actually been established.
- Use drafts only to prepare creation of new objects.
- Preserve provenance and idempotency during imports and provider integrations.