> ## Documentation Index > Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 credito 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 ```json theme={null} { "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