Appearance
Payment In
| Backlog field | Value |
|---|---|
| Story ID | AP-FIN-004 |
| Epic | Finance |
| Story type | Business workflow |
| Review status | Draft - business analyst and business owner review required |
| Source evidence | AppsPortal.Apis controller, application command/query handlers, validators, domain entities, and matching MFE workflow where available |
| Last source review | 2026-07-10 |
User story
As cashiers, I want to record, allocate, post, print, and reverse incoming payments so that customer and account balances reflect received funds.
Posting reference: AppsPortal Posting Ledger explains debit/credit construction. Delegation and Interaction Contracts explains module ownership, delegated commands, linked records, commit boundaries, and reversal propagation.
Acceptance criteria
- Only authorized users can view or execute the feature's actions.
- Required business data, active dependencies, tenant/branch scope, and current document state are validated.
- Invalid requests return actionable validation errors without applying a partial change.
- Search, list, view, print, and export operations use the same authorized business scope.
- Material create, edit, status, approval, posting, reversal, and integration actions are auditable where applicable.
- Financial or stock effects are applied atomically and no more than once.
Posting details
- Validate Draft state, open period, positive amount, currency/rate, payment method, detail allocations, and the selected Bank or Treasury hub.
- Resolve the header debit account from Treasury Account or Bank Account GL. Resolve detail credits from Customer Receivable (customer then category), Vendor Payable (vendor then category), or the explicitly selected Other GL.
- Add commission and VAT lines using Payment Method configuration, then delegate the balanced journal to Accounting.
- Finance creates the Bank/Treasury transaction and sequence, then delegates eligible customer/asset/opening-balance reconciliation to the owning modules.
- Journal, cash subledger, payment availability, reconciliations, credit effects, and Posted status commit together. Unpost reverses them through Sales, Fixed Assets, Accounting, and Finance.
General ledger posting
| Component | Debit | Credit | Account rule |
|---|---|---|---|
| Receipt | Bank/Treasury GL | Customer Receivable, Vendor Payable, or Other GL | Party account customer/vendor then category; other is explicit. |
| Commission/fee | Configured commission/fee account | Bank/Treasury GL | Only when payment method charges apply. |
| Fee VAT | Configured input tax/fee tax | Bank/Treasury GL | Only when configured taxable commission applies. |
Other module and document effects
| Area | Effect | Conditional/no effect |
|---|---|---|
| Bank/Treasury | Increases hub balance and creates linked transaction/sequence. | Rollback leaves no hub movement. |
| Sales/Fixed Assets/openings | Reconciles eligible invoice/opening due balances and updates availability. | Unallocated receipt remains available; no inventory effect. |
| Customer/vendor credit | Updates applicable party balance/credit. | Other-GL receipt has no party subledger effect. |
Core acceptance scenarios
- Given a valid Draft receipt with a configured bank/treasury and party accounts, when the cashier clicks Post, then the cash journal, bank/treasury subledger, payment availability, and eligible reconciliations are committed together.
- Given a linked invoice/opening/asset balance has changed or its period is closed, when the operation is attempted, then Unpost is rejected without reversing cash.
- Given the same Post request is retried after success, when the source is no longer Draft, then no duplicate journal, stock, balance, payment, or lifecycle effect is created.
Required and conditional data
Draft payment, date/open period, payment hub, amount, currency/rate, at least one allocation/detail, and payment method are required. Treasury is required for Treasury hub; bank account is required for Bank hub. Cheque number is required for cheque methods. Customer/vendor/source balance, tax, commission, reference, and reconciliation amount are conditional.
Account resolution
- Header debit: Treasury account or Bank Account GL.
- Customer credit: customer Receivable account, then customer category Receivable.
- Vendor credit where applicable: vendor Payable account, then vendor category Payable.
- Other detail: explicitly selected GL account.
- Commission/VAT: payment-method commission account and tax/VAT account; counterpart adjusts the bank/treasury header.
- Advance-payment tax requires the configured advance-payment tax account and selected tax account.
Clicking Post
Post validates Draft, hub account, details, party accounts, amount, method-specific data, period, and tax/commission setup. It debits bank/treasury, credits detail accounts, creates bank or treasury transaction records/codes, posts commission/tax lines, automatically reconciles eligible customer amounts against posted invoice balances, updates payment/detail and invoice due balances, marks Posted, and commits once.
Unpost
Unpost requires a Posted payment, open payment and linked reconciliation periods, a reversible posted journal, and intact bank/treasury/reconciliation links. It reverses the journal, removes bank/treasury movements, undoes invoice/opening-balance/asset reconciliations, restores customer/salesperson credit and payment availability, and returns the payment to its allowed unposted state atomically.
Frontend page coverage
The following UI coverage is sourced from the pulled MFE route configuration. A Module-level supporting artifact mapping is evidence of a reachable screen, but requires BA confirmation that it belongs to this story rather than a more specific feature story.
| Route/page | Component | Mode | Route permission/guard | Mapping confidence | Source |
|---|---|---|---|---|---|
| (module default) | PaymentInListComponent | List/navigation | Permission: AppFinancePermissions.PaymentIn_List; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/finance/src/app/remote-entry/transactions/transactions.module.ts:41 |
| add | AddPaymentInComponent | Add | Permission: AppFinancePermissions.PaymentIn_Add; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/finance/src/app/remote-entry/transactions/transactions.module.ts:52 |
| edit/:id | EditPaymentInComponent | Edit | Permission: AppFinancePermissions.PaymentIn_Edit; Guards: PolicyAuthGuard, preventPostedGuard | Explicit frontend feature rule | apps/finance/src/app/remote-entry/transactions/transactions.module.ts:63 |
| edit-payment-term/:id | EditPaymentTermComponent | Edit | Permission: AppFinancePermissions.PaymentTerms_Edit; Guards: PolicyAuthGuard | Feature token match | apps/finance/src/app/remote-entry/finance/finance.module.ts:186 |
| paymentin | MainPaymentInComponent | List/navigation | Permission: AppFinancePermissions.PaymentIn_List; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/finance/src/app/remote-entry/transactions/transactions.module.ts:32 |
| payment-method | MainPaymentMethodComponent | List/navigation | Permission: AppFinancePermissions.PaymentMethods_List; Guards: PolicyAuthGuard | Feature token match | apps/finance/src/app/remote-entry/finance/finance.module.ts:197 |
| view/:id | ViewPaymentInComponent | View/detail | Permission: AppFinancePermissions.PaymentIn_View; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/finance/src/app/remote-entry/transactions/transactions.module.ts:75 |
Observed frontend fields and validation
| Component | Control | Observed frontend rule | Component source |
|---|---|---|---|
| AddPaymentInComponent | amount | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | bankAccountId | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | description | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | glAccountId | Conditionally required/validated in component | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | IsAmountIncludesVat | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | IsCustomerAdvancedPayment | Conditionally required/validated in component | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | notes | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | paidBy | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | paidByDetailsId | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | paymentHub | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | paymentHubDetailId | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | PaymentInDate | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | paymentMethodId | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | rate | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | TaxId | Conditionally required/validated in component | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| EditPaymentInComponent | amount | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | bankAccountId | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | description | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | glAccountId | Conditionally required/validated in component | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | IsAmountIncludesVat | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | IsCustomerAdvancedPayment | Conditionally required/validated in component | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | notes | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | paidBy | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | paidByDetailsId | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | paymentHubDetailId | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | paymentInDate | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | paymentMethodId | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | rate | Required in component validator | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | TaxId | Conditionally required/validated in component | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| ViewPaymentInComponent | IsAmountIncludesVat | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/view-payment-in/view-payment-in.component.ts |
| ViewPaymentInComponent | IsCustomerAdvancedPayment | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/view-payment-in/view-payment-in.component.ts |
| ViewPaymentInComponent | TaxId | Visible control; optional or API-dependent | apps/finance/src/app/remote-entry/transactions/pages/paymentin/view-payment-in/view-payment-in.component.ts |
Observed frontend actions
| Component | Click action/handler | Business review requirement | Component source |
|---|---|---|---|
| AddPaymentInComponent | addNewRow | Add one initialized detail row without changing existing rows; apply defaults and line validators, preserve stable row identity, and exclude incomplete rows from Save/Post. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | cancel | Leave or close without persisting; warn when the current form has unsaved changes and restore the prior list/filter context. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | deleteLine | Available only in deletable states with Delete permission; identify the record in confirmation, call delete once, remove/refresh the list row on success, and retain the row with the API reason on failure. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | handleButtonClick | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | openCostPopup | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | openDialogSearch | Open the item/lookup/tracking dialog with the current warehouse, item, UOM, and remaining quantity context; accepted values must return to the correct line and cancel must not mutate it. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| AddPaymentInComponent | save | Validate the concrete form and line collection, prevent duplicate submission, persist once, show API field/business errors in context, and navigate/refresh only after success. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/add-payment-in/add-payment-in.component.ts |
| EditPaymentInComponent | addNewRow | Add one initialized detail row without changing existing rows; apply defaults and line validators, preserve stable row identity, and exclude incomplete rows from Save/Post. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | cancel | Leave or close without persisting; warn when the current form has unsaved changes and restore the prior list/filter context. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | handleButtonClick | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | onDelete | Available only in deletable states with Delete permission; identify the record in confirmation, call delete once, remove/refresh the list row on success, and retain the row with the API reason on failure. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | openCostPopup | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | openDialogSearch | Open the item/lookup/tracking dialog with the current warehouse, item, UOM, and remaining quantity context; accepted values must return to the correct line and cancel must not mutate it. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| EditPaymentInComponent | save | Validate the concrete form and line collection, prevent duplicate submission, persist once, show API field/business errors in context, and navigate/refresh only after success. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/edit-payment-in/edit-payment-in.component.ts |
| PaymentInListComponent | onDelete | Available only in deletable states with Delete permission; identify the record in confirmation, call delete once, remove/refresh the list row on success, and retain the row with the API reason on failure. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/payment-in-list/payment-in-list.component.ts |
| PaymentInListComponent | onEdit | Open the identified editable record only with Edit permission; posted/locked records remain blocked by route or action state and list context must be recoverable on return. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/payment-in-list/payment-in-list.component.ts |
| PaymentInListComponent | onPost | Available only for a postable Draft and Post permission; confirm the document, prevent a second submission, call the posting API, and refresh status, journal/stock links, and row actions. Failure must keep the pre-post state. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/payment-in-list/payment-in-list.component.ts |
| PaymentInListComponent | onUnPost | Available only for a postable Draft and Post permission; confirm the document, prevent a second submission, call the posting API, and refresh status, journal/stock links, and row actions. Failure must keep the pre-post state. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/payment-in-list/payment-in-list.component.ts |
| PaymentInListComponent | onView | Open the authorized record in view mode with its status, totals, lines, source and generated-document links; handle deleted, forbidden, and missing records without exposing stale data. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/payment-in-list/payment-in-list.component.ts |
| PaymentInListComponent | printout | Generate the printout for the selected record and authorized branch/tenant; use posted/current values and surface print, template, ZATCA/ETA, or popup failures without changing transaction state. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/payment-in-list/payment-in-list.component.ts |
| PaymentInListComponent | routeToJournalView | Open the authorized record in view mode with its status, totals, lines, source and generated-document links; handle deleted, forbidden, and missing records without exposing stale data. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/payment-in-list/payment-in-list.component.ts |
| ViewPaymentInComponent | handleButtonClick | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/view-payment-in/view-payment-in.component.ts |
| ViewPaymentInComponent | openCostPopup | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/view-payment-in/view-payment-in.component.ts |
| ViewPaymentInComponent | routeToJournalView | Open the authorized record in view mode with its status, totals, lines, source and generated-document links; handle deleted, forbidden, and missing records without exposing stale data. | apps/finance/src/app/remote-entry/transactions/pages/paymentin/view-payment-in/view-payment-in.component.ts |
Page-specific frontend acceptance criteria
- (module default) - List/navigation: Load an authorized paged/searchable list or navigation page; preserve filters/sort/paging and expose only permitted row and bulk actions. Security observed: Permission: AppFinancePermissions.PaymentIn_List; Guards: PolicyAuthGuard
- add - Add: Render permitted fields, required indicators, defaults, dependent lookups, validation, Save/Cancel, loading, success, and API-error states. Security observed: Permission: AppFinancePermissions.PaymentIn_Add; Guards: PolicyAuthGuard
- edit/:id - Edit: Load the identified record, enforce state/permission field locks, preserve concurrency identity, validate changes, and return without losing filters. Security observed: Permission: AppFinancePermissions.PaymentIn_Edit; Guards: PolicyAuthGuard, preventPostedGuard
- edit-payment-term/:id - Edit: Load the identified record, enforce state/permission field locks, preserve concurrency identity, validate changes, and return without losing filters. Security observed: Permission: AppFinancePermissions.PaymentTerms_Edit; Guards: PolicyAuthGuard
- paymentin - List/navigation: Load an authorized paged/searchable list or navigation page; preserve filters/sort/paging and expose only permitted row and bulk actions. Security observed: Permission: AppFinancePermissions.PaymentIn_List; Guards: PolicyAuthGuard
- payment-method - List/navigation: Load an authorized paged/searchable list or navigation page; preserve filters/sort/paging and expose only permitted row and bulk actions. Security observed: Permission: AppFinancePermissions.PaymentMethods_List; Guards: PolicyAuthGuard
- view/:id - View/detail: Load an authorized immutable/detail representation with status-aware actions, linked records, print/export where exposed, and not-found/forbidden handling. Security observed: Permission: AppFinancePermissions.PaymentIn_View; Guards: PolicyAuthGuard