Cash Receipts

CEF Core supports five categories of cash receipts, each with distinct GL treatment and processing rules:

Post a cash receipt via POST /api/v1/cash/transactions with an idempotency key header. The amount must be a positive number. Requires the ADMIN, TREASURY, or SYSTEM_ADMIN role.

POST /api/v1/cash/transactions
Content-Type: application/json
x-idempotency-key: receipt-20260315-001

{
  "account_id": "uuid-of-operating-checking",
  "transaction_date": "2026-03-15",
  "transaction_type": "DEPOSIT",
  "amount": 12500.00,
  "description": "Loan payment - Grace Community Church",
  "reference_number": "CHK-4821"
}

Request Fields

Many receipts are created automatically when related transactions occur in other modules. You do not need to manually record these:

• ✓Loan Payment Processing: When a loan payment is posted in the Loans module, a corresponding DEPOSIT transaction is auto-created in the cash account and a journal entry is posted to the GL.
• ✓New Note Investments: When an investor purchases a note via the Investor Notes module, the cash receipt is recorded automatically with the note ID as the reference number.
• ✓Interest Accrual: The scheduled tenantAccrualCheck job (every 15 minutes) processes accrued interest and creates the corresponding cash and GL entries.

Manual receipts are typically needed for miscellaneous income, one-time donations, insurance refunds, or corrections.

CEF Core integrates with Plaid to automatically import bank transactions. Imported deposits are matched against internal receipt records using three criteria:

1. Amount match: The bank deposit amount matches the internal receipt amount exactly.
2. Date proximity: The bank transaction date falls within a configurable window (typically 1-3 business days) of the internal transaction date.
3. Reference number: When available, the check number or wire reference is compared for positive identification.

Import Schedule

• Hourly: The syncBankTransactions job pulls new transactions from Plaid every hour.
• Daily: The importBankActivity job runs at 2:05 AM UTC for a comprehensive daily reconciliation pull.

Unmatched bank deposits appear in the reconciliation queue for manual review and matching.

Every cash receipt generates a corresponding double-entry journal entry in the General Ledger. The debit always goes to the appropriate cash account:

The GL journal entry ID is stored on the cash transaction record in the gl_je_id column, providing a direct link between the cash ledger and the general ledger for audit and reconciliation purposes.

Retrieve receipt history using the transactions endpoint with filters:

GET /api/v1/cash/transactions?accountId={uuid}&limit=50

Response:
{
  "transactions": [
    {
      "transaction_id": "uuid",
      "account_id": "uuid",
      "account_name": "Operating Checking",
      "transaction_date": "2026-03-15",
      "transaction_type": "DEPOSIT",
      "amount": "12500.00",
      "description": "Loan payment - Grace Community Church",
      "reference_number": "CHK-4821",
      "status": "POSTED",
      "created_at": "2026-03-15T14:30:00Z"
    }
  ],
  "count": 1
}

Filter by accountId to view receipts for a specific bank account. Results are ordered by transaction date descending, with a maximum of 100 records per request.

All cash receipt operations are recorded in the immutable audit trail:

• ✓CREATE events: Every new receipt records the user ID, email, role, amount, and full transaction details in the tamper-evident audit log.
• ✓READ events: Viewing receipt lists or individual account details is logged asynchronously for compliance visibility.
• ✓Failed attempts: If a receipt fails validation or database insertion, the failure is also logged with the error message.