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.
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" }
}
}
}
}
apps/api/src/database/entities/PaymentMeans.ts · domain: financial-graph · tier: Main
