Payment Means

A PaymentMeans record represents a payment instrument — a bank account, card, or paper check — linked to a financial transaction as either the debtor or creditor side. It acts as the bridging entity between transactions and the specific financial instrument used, referencing a normalized Account, Card, or Check entity to carry instrument-specific details. Every payment_means row is workspace-scoped and may be associated with a Company or a People record that owns or operates the instrument. The entity is a primary MCP sync target, and its sourceWorkspaceConnector tracks which connector ingested the row.

Naming	Value
Object	Payment Means
Resource type (JSON:API `type`)	`payment_means`
Collection / records root	`payment_means`
REST base	`/v1/payment-means`
Entity class	`PaymentMeans`

API operations

Operation	Method & path	Status
List	`GET /v1/payment-means`	✅ Implemented
Retrieve	`GET /v1/payment-means/{id}`	✅ Implemented
Create	`POST /v1/payment-means`	🟡 Planned
Update	`PATCH /v1/payment-means/{id}`	🟡 Planned
Delete	`DELETE /v1/payment-means/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
payment_means_id	string, UUID, 🔒 system	✅ Yes	unique; defaultRaw: gen_random_uuid()	—	Public stable identifier for the payment instrument. Used in all API responses; the internal pk is never exposed.
name	string	⚪ No	length ≤ 255; nullable	—	Human-readable label for the payment instrument (e.g. ‘Qonto EUR Operating’, ‘Visa **** 4321’). Populated by connectors or manually. Previously stored as digital_wallet_id before the January 2026 schema refactor.
payment_means_external_id	string	⚪ No	length ≤ 255; nullable	—	Connector-assigned external identifier for this payment instrument, enabling deduplication and idempotent upserts during MCP sync. Scoped to the connector — not globally unique.
created_at	Date, 🔒 system	✅ Yes	set on insert via onCreate lifecycle hook; never null	—	Timestamp of when the payment_means row was created in Well.
updated_at	Date, 🔒 system	⚪ No	set on insert and update via onUpdate lifecycle hook; nullable	—	Timestamp of the most recent update to this row.
deleted_at	Date	⚪ No	nullable; soft-delete sentinel	—	When set, marks the row as soft-deleted. All repository queries must filter deleted_at IS NULL. A compound index idx_payment_means_workspace_deleted covers (workspace, deleted_at) for efficient scoped queries.

Relationships

Name	Type	Required	Description
workspace	to-one (Workspace)	⚪ No	Tenant boundary. Every payment_means must belong to a Workspace. Nullable FK in the DB but treated as mandatory in practice for all workspace-scoped reads. Compound index idx_payment_means_workspace_deleted covers this FK together with deleted_at.
account	to-one (Account)	⚪ No	The bank account backing this payment instrument. Populated when the instrument is an IBAN/bank-account type. Carries IBAN, BIC, routing number, currency, and balance data on the Account entity. Indexed via idx_payment_means_account.
card	to-one (Card)	⚪ No	The card entity backing this payment instrument. Populated when the instrument is a credit, debit, or virtual card. The Card entity carries last_four_digits, brand, type (credit/debit/prepaid/corporate/virtual), cardholder_name, and expiry dates. Indexed via idx_payment_means_card.
check	to-one (Check)	⚪ No	The check entity backing this payment instrument. Populated when the instrument is a paper cheque. The Check entity carries CMC7 line, check_number, and issue_date. Indexed via idx_payment_means_check.
company	to-one (Company)	⚪ No	The company that owns or is associated with this payment instrument. Used when the instrument is held by a legal entity (e.g. a vendor’s IBAN, a corporate card). Added in Migration20260109082834. Indexed via idx_payment_means_company.
people	to-one (People)	⚪ No	The individual person associated with this payment instrument. Used when the instrument is held by a natural person (e.g. a personal IBAN, an individual cardholder). Added in Migration20260109082834. Indexed via idx_payment_means_people.
sourceWorkspaceConnector	to-one (WorkspaceConnector)	⚪ No	The workspace connector that created or last synced this row. Populated for all MCP-connector-ingested payment_means rows. NULL indicates a manually created or pipeline-inferred row. Used for provenance tracking and backfill auditing (see Migration20260406100000_expand_mcp_sync_models and Migration20260529093038_backfill_orphan_source_workspace_connector).

System-computed

payment_means_id is generated via gen_random_uuid() as a PostgreSQL server-side default. It is unique and immutable after insert.
created_at is set once at insert time via MikroORM onCreate lifecycle hook. It is never updated.
updated_at is set at insert and refreshed on every update via onUpdate lifecycle hook.
deleted_at is null on active rows. Setting it to a non-null timestamp soft-deletes the row. The compound index idx_payment_means_workspace_deleted (workspace, deleted_at) enables efficient active-record queries per workspace.
payment_means_external_id is the connector deduplication key. The connector sync pipeline uses this to perform idempotent upserts: if a row with the same payment_means_external_id already exists in the workspace scope, the existing row is updated rather than a duplicate created.
sourceWorkspaceConnector is set automatically by the MCP sync pipeline when a row is ingested from a connector. It remains NULL for rows created through invoice parsing, manual entry, or other non-connector paths.
The name column was introduced in Migration20260102111942 as a rename of the legacy digital_wallet_id column from the original flat-column schema. It now serves as a generic free-text label regardless of instrument type.
Exactly one of account, card, or check should be set on a given row — this is a polymorphic instrument pattern. Both company and people may be set simultaneously (e.g. a personal card belonging to a company employee), or only one may be set, or neither.
Transactions reference payment_means via debtor_payment_means_pk and creditor_payment_means_pk. A single payment_means row can appear on many transactions over time.

Example

{
  "data": {
    "type": "payment_means",
    "id": "b4e2f1a7-83c9-4d6e-9a11-2f3c8e7b0d45",
    "attributes": {
      "payment_means_id": "b4e2f1a7-83c9-4d6e-9a11-2f3c8e7b0d45",
      "name": "Qonto EUR Operating",
      "payment_means_external_id": "pm_acc_9x2k7w",
      "created_at": "2026-01-15T09:22:00.000Z",
      "updated_at": "2026-04-03T14:05:30.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "c91f3d82-1a4b-4e77-b6f2-0a9d5c3e8f12" }
      },
      "account": {
        "data": { "type": "account", "id": "f3d89b21-7e42-4c5a-b601-d8e3a9c4071f" }
      },
      "company": {
        "data": { "type": "company", "id": "0ae71c3b-6f4d-4880-a92e-5b7c1d9e2f08" }
      },
      "people": {
        "data": null
      },
      "card": {
        "data": null
      },
      "check": {
        "data": null
      },
      "sourceWorkspaceConnector": {
        "data": { "type": "workspace_connector", "id": "7a3b8c12-d4e9-4f21-b5a7-1c6d2e9f0374" }
      }
    }
  }
}

_{Source: apps/api/src/database/entities/PaymentMeans.ts · domain: financial-graph · tier: Main}

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example