Receipt Vouchers

Receipt vouchers (سندات القبض) are multi-line receipt documents used for complex receipts from business partners. Each voucher can contain multiple lines, each targeting a different GL account, payment method, or check number. When approved, the system automatically creates a balanced journal entry. The print endpoint provides enriched data with company info and amount in words (Arabic and English).

Purpose

Record multi-line receipts from business partners
Support mixed payment methods within a single voucher (cash, check, bank transfer, card)
Auto-generate voucher numbers via the sequence service
Create journal entries automatically on approval
Reverse journal entries on cancellation
Provide printable voucher data with amount in words and company letterhead info
Track cross-references to other documents (invoices, sales orders, etc.)

Entity Attributes

Receipt Voucher (Header)

Field	Type	Description
`id`	`bigint`	Primary key
`company_id`	`bigint`	FK to `companies`
`branch_id`	`bigint?`	FK to `branches`
`voucher_number`	`string`	Auto-generated sequence number (e.g., `RV-2026-0001`)
`date`	`date`	Voucher date
`partner_id`	`bigint?`	FK to `business_partners`
`total_amount`	`decimal(12,3)`	Total receipt amount
`amount_in_words`	`string?`	Amount written in words (stored value)
`payment_method`	`enum`	Primary method: `cash`, `check`, `bank_transfer`, `card`, `mixed`
`receiving_account_id`	`bigint?`	FK to `accounts` (primary receiving GL account)
`bank_account_id`	`bigint?`	FK to `bank_accounts`
`check_number`	`string?`	Check number (header level)
`check_date`	`date?`	Check date
`check_bank`	`string?`	Issuing bank name
`description`	`string?`	English description
`description_ar`	`string?`	Arabic description
`reference_type`	`string?`	Related document type (e.g., `invoice`, `sales_order`)
`reference_id`	`bigint?`	Related document ID
`reference_number`	`string?`	Related document number
`cost_center_id`	`bigint?`	FK to `cost_centers`
`currency_id`	`bigint?`	FK to `currencies`
`exchange_rate`	`decimal(12,6)?`	Exchange rate if non-base currency
`status`	`enum`	`draft`, `approved`, `cancelled`
`journal_entry_id`	`bigint?`	FK to `journal_entries` (set on approval)
`created_by`	`bigint`	FK to `users`
`approved_by`	`bigint?`	FK to `users`
`approved_at`	`datetime?`	Approval timestamp
`created_at`	`timestamp`	Creation timestamp
`updated_at`	`timestamp`	Last update timestamp
`deleted_at`	`timestamp?`	Soft-delete timestamp

Receipt Voucher Line

Field	Type	Description
`id`	`bigint`	Primary key
`receipt_voucher_id`	`bigint`	FK to `receipt_vouchers`
`account_id`	`bigint?`	FK to `accounts` (revenue/credit account)
`partner_account_id`	`bigint?`	FK to `accounts` (partner's AR account)
`amount`	`decimal(12,3)`	Line amount
`payment_method`	`enum?`	Line-level payment method override
`bank_account_id`	`bigint?`	Line-level bank account
`check_number`	`string?`	Line-level check number
`description`	`string?`	Line description

Relationships

Lifecycle

API Endpoints

Method	Path	Description
`GET`	`/api/accounting/receipt-vouchers`	List receipt vouchers (paginated)
`POST`	`/api/accounting/receipt-vouchers`	Create a new receipt voucher (draft)
`GET`	`/api/accounting/receipt-vouchers/{id}`	Get a single receipt voucher with lines
`PUT`	`/api/accounting/receipt-vouchers/{id}`	Update a receipt voucher (draft only)
`DELETE`	`/api/accounting/receipt-vouchers/{id}`	Soft-delete a receipt voucher (draft only)
`POST`	`/api/accounting/receipt-vouchers/{id}/approve`	Approve and create journal entry
`POST`	`/api/accounting/receipt-vouchers/{id}/cancel`	Cancel and reverse journal entry
`GET`	`/api/accounting/receipt-vouchers/{id}/print`	Get printable voucher data

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `draft`, `approved`, `cancelled`
`partner_id`	integer	No	Filter by business partner
`branch_id`	integer	No	Filter by branch
`date_from`	date	No	Filter vouchers on or after this date
`date_to`	date	No	Filter vouchers on or before this date
`page`	integer	No	Page number (25 per page)

Request/Response Examples

Create Receipt Voucher

Request POST /api/accounting/receipt-vouchers

curlDart

bash

curl -X POST https://moon-erp.test/api/accounting/receipt-vouchers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "date": "2026-02-23",
    "partner_id": 8,
    "total_amount": "7500.000",
    "payment_method": "bank_transfer",
    "receiving_account_id": 15,
    "bank_account_id": 1,
    "description": "Customer payment for Jan/Feb invoices",
    "description_ar": "دفعة عميل لفواتير يناير وفبراير",
    "cost_center_id": 1,
    "currency_id": 1,
    "branch_id": 1,
    "lines": [
      {
        "account_id": 60,
        "partner_account_id": 10,
        "amount": "5000.000",
        "description": "Invoice #INV-2026-0008"
      },
      {
        "account_id": 60,
        "partner_account_id": 10,
        "amount": "2500.000",
        "description": "Invoice #INV-2026-0011"
      }
    ]
  }'

dart

final response = await http.post(
  Uri.parse('https://moon-erp.test/api/accounting/receipt-vouchers'),
  headers: {
    'Authorization': 'Bearer $token',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: jsonEncode({
    'date': '2026-02-23',
    'partner_id': 8,
    'total_amount': '7500.000',
    'payment_method': 'bank_transfer',
    'receiving_account_id': 15,
    'bank_account_id': 1,
    'description': 'Customer payment for Jan/Feb invoices',
    'description_ar': 'دفعة عميل لفواتير يناير وفبراير',
    'cost_center_id': 1,
    'currency_id': 1,
    'branch_id': 1,
    'lines': [
      {
        'account_id': 60,
        'partner_account_id': 10,
        'amount': '5000.000',
        'description': 'Invoice #INV-2026-0008',
      },
      {
        'account_id': 60,
        'partner_account_id': 10,
        'amount': '2500.000',
        'description': 'Invoice #INV-2026-0011',
      },
    ],
  }),
);

Response 201 Created

json

{
  "data": {
    "id": 1,
    "company_id": 1,
    "branch_id": 1,
    "voucher_number": "RV-2026-0001",
    "date": "2026-02-23",
    "partner_id": 8,
    "partner": {
      "id": 8,
      "name": "Al Safat Trading",
      "name_ar": "شركة الصفاة التجارية"
    },
    "total_amount": "7500.000",
    "amount_in_words": null,
    "payment_method": "bank_transfer",
    "payment_method_label": "Bank Transfer",
    "receiving_account_id": 15,
    "receiving_account": {
      "id": 15,
      "code": "1201001",
      "name": "NBK Main Account"
    },
    "bank_account_id": 1,
    "check_number": null,
    "check_date": null,
    "check_bank": null,
    "description": "Customer payment for Jan/Feb invoices",
    "description_en": "Customer payment for Jan/Feb invoices",
    "description_ar": "دفعة عميل لفواتير يناير وفبراير",
    "reference_type": null,
    "reference_id": null,
    "reference_number": null,
    "status": "draft",
    "status_label": "Draft",
    "journal_entry_id": null,
    "cost_center_id": 1,
    "currency_id": 1,
    "exchange_rate": null,
    "lines": [
      {
        "id": 1,
        "account_id": 60,
        "partner_account_id": 10,
        "amount": "5000.000",
        "payment_method": null,
        "payment_method_label": null,
        "bank_account_id": null,
        "check_number": null,
        "description": "Invoice #INV-2026-0008"
      },
      {
        "id": 2,
        "account_id": 60,
        "partner_account_id": 10,
        "amount": "2500.000",
        "payment_method": null,
        "payment_method_label": null,
        "bank_account_id": null,
        "check_number": null,
        "description": "Invoice #INV-2026-0011"
      }
    ],
    "created_by": 1,
    "approved_by": null,
    "approved_at": null,
    "created_at": "2026-02-23T10:00:00.000000Z",
    "updated_at": "2026-02-23T10:00:00.000000Z"
  }
}

Print Receipt Voucher

Request GET /api/accounting/receipt-vouchers/1/print

Response 200 OK

json

{
  "data": {
    "voucher": {
      "id": 1,
      "voucher_number": "RV-2026-0001",
      "date": "2026-02-23",
      "partner": { "id": 8, "name": "Al Safat Trading" },
      "total_amount": "7500.000",
      "payment_method": "bank_transfer",
      "status": "approved",
      "lines": [
        { "account_id": 60, "amount": "5000.000", "description": "Invoice #INV-2026-0008" },
        { "account_id": 60, "amount": "2500.000", "description": "Invoice #INV-2026-0011" }
      ]
    },
    "company": {
      "name": "Moon ERP Co.",
      "name_ar": "شركة مون",
      "address": "Kuwait City, Block 5",
      "address_ar": "مدينة الكويت، قطعة 5",
      "phone": "+965-12345678",
      "email": "info@moonerp.com",
      "tax_number": "123456789",
      "commercial_register": "CR-2024-001",
      "logo": "logo.png"
    },
    "branch": {
      "name": "Main Branch",
      "name_ar": "الفرع الرئيسي",
      "address": "Kuwait City",
      "phone": "+965-12345678"
    },
    "amount_in_words_en": "Seven Thousand Five Hundred Kuwaiti Dinars",
    "amount_in_words_ar": "سبعة آلاف وخمسمائة دينار كويتي",
    "print_date": "2026-02-23",
    "printed_by": "Admin"
  }
}

Generated Journal Entry

When a receipt voucher is approved, the system creates a posted journal entry. The debit goes to the receiving account, and the credit lines come from the voucher lines.

Line	Account	Debit	Credit	Description
1	Receiving account (e.g., NBK Main Account)	7,500.000	--	Total received
2	Line 1 account (e.g., AR/Revenue)	--	5,000.000	Invoice #INV-2026-0008
3	Line 2 account (e.g., AR/Revenue)	--	2,500.000	Invoice #INV-2026-0011

Business Rules

Rule	Description
Draft-only edits	Vouchers can only be updated or deleted while in `draft` status
Auto voucher number	`voucher_number` is auto-generated via the sequence service on creation
Lines replaced on update	When updating with `lines`, all existing lines are replaced with the new set
Approval creates JE	Approving a draft voucher creates a posted journal entry
Cancel reverses JE	Cancelling an approved voucher reverses the associated journal entry
Multi-line support	Each line can have its own account, amount, payment method, and check number
Mixed payments	Set `payment_method` to `mixed` when lines use different payment methods
Company scoped	All vouchers are filtered by the authenticated user's company
Print enrichment	The print endpoint returns company/branch info, amount in words (Arabic/English), and all relationships

Permissions

Permission	Description
`accounting.receipt-vouchers.view`	View receipt vouchers and print
`accounting.receipt-vouchers.create`	Create new receipt vouchers
`accounting.receipt-vouchers.update`	Update draft receipt vouchers
`accounting.receipt-vouchers.approve`	Approve draft receipt vouchers
`accounting.receipt-vouchers.cancel`	Cancel approved receipt vouchers

Receipt Vouchers ​

Purpose ​

Entity Attributes ​

Receipt Voucher (Header) ​

Receipt Voucher Line ​

Relationships ​

Lifecycle ​

API Endpoints ​

Query Parameters ​

Request/Response Examples ​

Create Receipt Voucher ​

Print Receipt Voucher ​

Generated Journal Entry ​

Business Rules ​

Permissions ​