Document Payment Methods

Overview

The document-payment-methods module manages per-document-type payment method configurations for each business. While the business-payment-methods module controls which payment methods a business has enabled globally, this module controls which of those payment methods are available for each specific document type (sale, purchase, order bill, etc.) along with document-specific flags.

This is a configuration module — it does not process payments, but it determines what options are presented to users when creating documents.

---

Domain Concepts

Document Payment Method

A configuration record that associates a payment method with a document type for a specific business.

Field	Type	Description
businessId	UUID	The owning business
documentType	string	Document type (e.g. sale, purchase, orderBill)
paymentMethodId	UUID	Reference to the global payment method catalog
paymentOrder	integer	Display order within the document type (1-based)
generateElectronicTaxDocument	boolean	Whether this method triggers FEL generation
requireCustomerAccount	boolean	Whether a customer account must be linked
requireSupplierAccount	boolean	Whether a supplier account must be linked

Supported Document Types

The following document types support payment method configuration (defined in DOCUMENT_TYPES_SUPPORTING_PAYMENT_METHODS):

• sale — Retail point-of-sale transactions
• orderBill — Restaurant order bills
• purchase — Purchase documents
• contractorAssignment — Contractor payment assignments
• accountsReceivableReceipt — AR receipt processing
• accountsPayablePayment — AP payment processing
• materialConsumption — Material consumption documents

Unique Constraint

Each combination of (businessId, documentType, paymentMethodId) is unique. A business cannot have the same payment method configured twice for the same document type.

---

Architecture

The module follows hexagonal architecture:

domain/
  document-payment-methods-repository.domain.ts  → Port interface + injection token
application/
  document-payment-methods.service.ts             → Use cases + default seeding
infrastructure/
  document-payment-methods.repository.ts          → Kysely adapter
interfaces/
  document-payment-methods.controller.ts          → HTTP endpoints
  dtos/
    create-document-payment-method.dto.ts         → Create request schema
    update-document-payment-method.dto.ts         → Update request schema
  query/
    paginate-document-payment-methods.query.ts    → Pagination/filter query

Dependency flow: Controller → Service → Repository Interface (domain port) ← Repository Implementation (infrastructure)

The repository is injected via a string token (DOCUMENT_PAYMENT_METHODS_REPOSITORY), enabling dependency inversion.

---

Main Use Cases

1. CRUD Operations

Standard create, read, update, delete for individual document payment method records.

2. Business Creation Seeding

When a new business is created (OnCreateBusinessEvent), the service automatically seeds default payment method configurations for all supported document types. This runs in a single database transaction and is idempotent — existing records are not duplicated.

Default configurations include:

• Sale/Order/OrderBill: Cash + Accounts Receivable (both with FEL enabled)
• Purchase: Cash + Accounts Payable
• Contractor Assignment: Accounts Payable + Cash + Courtesy
• AP/AR Payments: Cash, Bank Transfer, Check, Credit Card, Debit Card, Courtesy
• Material Consumption: Material Consumption + Cash + Accounts Receivable

3. Paginated Listing with Enriched Data

The list endpoint joins with the paymentMethod table to return enriched records including:

• paymentMethodName — display name
• paymentGroup — group classification
• generatesAccountsReceivable — AR flag
• generatesAccountsPayable — AP flag

---

API Endpoints

Method	Path	Description
POST	/document-payment-methods	Create a document payment method
GET	/document-payment-methods	List with pagination and filters
GET	/document-payment-methods/:id	Get by ID
PATCH	/document-payment-methods/:id	Update
DELETE	/document-payment-methods/:id	Delete

Query Parameters (GET list)

Parameter	Type	Required	Description
businessId	UUID	No	Filter by business
documentType	string	No	Filter by document type
size	number	No	Page size
page	number	No	Page number
orderBy	string	No	Sort field (documentType)
order	asc/desc	No	Sort direction
search	string	No	Search by payment method name

Example: Create

POST /document-payment-methods
{
  "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "documentType": "sale",
  "paymentMethodId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "paymentOrder": 1,
  "createdBy": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "generateElectronicTaxDocument": true,
  "requireCustomerAccount": false,
  "requireSupplierAccount": false
}

Example: Update

PATCH /document-payment-methods/:id
{
  "paymentOrder": 2,
  "generateElectronicTaxDocument": false,
  "updatedBy": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}

---

Cross-Module Dependencies

Consumed by

• order-bill.service.ts — Queries documentPaymentMethod table directly (via Kysely) to check if electronic tax document generation is required for a given payment method on ORDER_BILL documents.

Depends on

• businesses — Listens to OnCreateBusinessEvent for seeding defaults
• payment-methods — References the global payment method catalog (via paymentMethodId FK and getPaymentMethodByKey utility)

---

Design Decisions

1. Hard delete — Document payment methods are hard-deleted (not soft-deleted) since they are configuration records, not transactional data.
2. Idempotent seeding — The default seeding checks for existing records before inserting, preventing duplicates even if the event fires multiple times.
3. FEL flag per document-type — The generateElectronicTaxDocument flag is scoped to the document-type level (not globally), allowing businesses to require FEL for sales but not for purchases.