Vendor Credit and Payment Forms
AccuArk uses three forms to manage vendor credit financial transactions. Article 81 explains vendor credit concepts and workflows at a high level. This article documents each form interface field by field, covering every control, grid column, validation rule, and save behavior as implemented in the application.
Manage Negative Balance Dialog
The Manage Negative Balance dialog (FrmManageVendorNegativeBalance) appears when a purchase order payment results in a negative balance, meaning the vendor owes you money due to an overpayment or excess return credit.
When It Appears
This dialog opens automatically during the PO payment workflow whenever the system detects that a payment would push the PO balance below zero. It asks how you want to handle the overpayment before proceeding.
Form Layout
The dialog is a fixed-size tool window centered on screen with the title "Manage Vendor Purchase Order Negative Balance". It contains:
- Instruction Text -- A read-only text box at the top displaying: "This purchase order has a negative balance. How would you like to manage this balance?" The scroll position is reset to the top when the form loads so the full message is visible.
- Options Group -- A group box containing three radio button choices
- Proceed / Cancel Buttons -- Action buttons at the bottom
Radio Button Options
| Option | Control Name | Label Text | Description |
|---|---|---|---|
| Hold for Later | rbHoldForLater | "Keep the Balance and Process Later" | Leaves the negative balance on the PO for future resolution. This is the default pre-selected option when the form loads. |
| Apply Vendor Credit | rbApplyVendorCredit | "Apply as Vendor Credit for future purchases" | Converts the overpayment into a vendor credit record that can be applied to future PO payments from this vendor. |
| Request Refund | rbRequestRefund | "Get Refund from the Vendor" | Marks the overpayment for a vendor refund. This option is disabled when the vendor ID is zero (no vendor assigned to the PO). |
Internal Enum
The form uses a NegativeBalanceOption enum with five values: None, HoldForLater, ApplyVendorCredit, RequestRefund, and OffsetOtherPurchaseOrder. The SelectedOption property is set to None by default and updated to match the chosen radio button when Proceed is clicked. The OffsetOtherPurchaseOrder value exists in the enum but does not have a corresponding radio button in the current form.
Button Behavior
- Proceed -- Validates that a radio button is selected. If no option is chosen (SelectedOption is None), displays a warning: "Please select an option to manage the negative balance." Otherwise, sets SelectedOption to the matching enum value and returns DialogResult.OK.
- Cancel -- Returns DialogResult.Cancel and closes the form without changes.
Apply Vendor Credit Form
The Apply Vendor Credit form opens from the PO payment workflow when the user chooses to apply existing vendor credits against a purchase order bill. It displays all available credits for the vendor at the current location and lets the user select which credits to apply and how much of each.
Header Fields
All header fields are read-only and populated from properties set by the calling form before the dialog opens:
| Field | Control | Description |
|---|---|---|
| Bill ID | tbBillId | The accounts payable bill being paid |
| Vendor | tbVendorInfo | Vendor name and details, displayed in a multi-line read-only group box |
| Location | tbCreditLocation | The location where credits are being applied, displayed in a multi-line read-only group box |
| Purchase Order | tbPurchaseOrderId | The purchase order being paid |
| Purchase Order Balance | tbBalance | The current outstanding balance on the PO, formatted to two decimal places |
Credits Grid
The Available Credits grid (dgvCredits) is the main working area of the form. It loads all non-cancelled vendor credits with available balance greater than zero for the current vendor and location.
Grid Columns
| Column | Name | Type | Visible | Description |
|---|---|---|---|---|
| Select | selectCreditToApply | Checkbox | Yes | Toggles whether this credit is included in the application |
| ID | creditId | Text | No (hidden) | The vendor credit record ID |
| Credit Account ID | creditAccountId | Text | No (hidden) | The GL account ID associated with the credit |
| Account | creditToAccount | Text | Yes | The GL account name the credit is linked to |
| PO # | creditPO | Text | Yes | The purchase order that originally generated this credit |
| Amount | creditAmount | Text (currency) | Yes | The total credit amount originally issued |
| Available | availableAmount | Text (currency) | Yes | The remaining unused credit balance |
| Applied | amountToApply | Text (currency) | Yes | The amount being applied from this credit toward the current PO payment |
Auto-Allocation Logic
When the form loads, credits are automatically pre-allocated against the PO balance:
- The system starts with the full PO balance as the remaining amount to cover
- Credits are processed in the order returned by the database query
- For each credit, if remaining balance is still positive:
- If the credit's available amount is less than or equal to the remaining balance, the full available amount is allocated and the credit is selected
- If the credit's available amount exceeds the remaining balance, only the remaining balance amount is allocated and the credit is selected
- Once the PO balance is fully covered, any additional credits are left unselected with an applied amount of 0.00
Checkbox Toggle Behavior
Clicking a credit's Select checkbox toggles its selection state:
- Deselecting a checked credit -- Unchecks the box, sets the applied amount to 0.00, and decrements the total credit applied by the previous applied amount
- Selecting an unchecked credit -- Only allowed if there is remaining PO balance to cover. If allowed, checks the box and allocates up to the lesser of the available credit or the remaining balance. If the full PO balance is already covered, shows an error: "No remaining balance to apply credits."
Amount Editing
Clicking the Applied amount cell opens the FrmEnterNumber dialog, which allows direct entry of a custom amount. The dialog title shows "Enter New Amount to Apply" and the subtitle shows the available credit balance. Validation rules:
- The entered amount cannot be negative (error: "Credit cannot be a negative number!")
- The entered amount cannot exceed the credit's available amount (error: "You cannot apply more than the available credit.")
- The total of all applied credits cannot exceed the PO balance (error: "You cannot apply more than the total purchase order balance.")
- If the new amount is greater than zero, the checkbox is automatically checked; if zero, it is unchecked
Summary Fields
Below the grid, three summary fields are recalculated after every change via the UpdateCreditCalculations method:
| Field | Control | Calculation |
|---|---|---|
| Total Available Credit | tbCreditAvailableAmount | Sum of all available amounts across all credit rows |
| Total Credit Applied | tbTotalCreditApplied | Sum of applied amounts for selected credits only |
| Balance After Credit | tbBalanceAfterCreditApplied | PO Balance minus Total Credit Applied |
Credit To Account Dropdown
The Credit To Account dropdown (cbCreditToAccount) lets you choose the GL account to credit when applying vendor credits. It loads all active accounts from chart_master, grouped by account type with entries indented by their hierarchy level. A "NONE" option with value 0 appears at the top. The dropdown defaults to the vendor's expense account (retrieved via DbVendor.GetVendorExpenseAccount). If the vendor has no expense account set, "NONE" is selected.
Notes Field
A free-text Notes field (tbNotes) in a group box at the bottom. The notes text is appended to each credit application transaction description when saved.
Save and Close Behavior
Clicking "Apply Credits & Close" triggers the following for each selected credit row with an amount greater than zero:
- Creates an AccountTransaction record with:
- PaymentType set to VendorCredit
- PaymentStatus set to Completed
- PaymentMethod set to Other
- The credit amount as both the credit and debit amounts
- A reference string identifying the vendor credit ID and originating PO
- A description noting the PO being paid and the current date/time, plus any notes
- Calls DbVendorCredit.ApplyVendorCredit() to decrement the credit's available balance
- Creates an audit record linking the transaction, credit, vendor, locations, and PO details
If all credits are saved successfully, the form returns DialogResult.OK. If any error occurs, an error message is displayed and the form remains open.
During save, the Close and Save buttons are disabled and a progress bar appears in the status strip.
Credit Vendor Payments Form
The Credit Vendor Payments form (FrmCreditVendorPayments) is used when creating a new vendor credit from existing payments -- essentially reversing payments into credits. This form selects which payments to convert and how much of each payment to credit.
Permission Check
The form checks permissions on load. The user must have either Management or Accounting access. If neither is present, the form displays an access denied message and closes immediately: "Access Denied: Unfortunately, you do not have the necessary permissions to access this feature. This section requires either Management or Accounting privileges."
Header Fields
| Field | Control | Description |
|---|---|---|
| Credit ID | tbCreditId | Shows the vendor credit record ID, or "New" if the credit has not been saved yet (Id is 0 or less) |
| Vendor | tbVendorInfo | Vendor name and details in a multi-line read-only group box |
| Credit Location | tbCreditLocation | The location for this credit |
| Credit Date | dtpCreditDate | A disabled DateTimePicker showing the credit date |
| Purchase Order | tbPurchaseOrderId | The linked purchase order ID |
| Total Credit Amount | tbCreditAmount | The credit amount with a currency symbol prefix, displayed in bold. This value comes from VendorCredit.VendorCreditAmount. |
Payments Grid
The Payments grid (dgvPayments) shows all account transactions associated with the vendor credit's linked bill.
Grid Columns
| Column | Name | Type | Visible | Description |
|---|---|---|---|---|
| Select | selectPaymentToCredit | Checkbox | Yes | Toggles whether this payment is included in the credit |
| ID | paymentId | Text | No (hidden) | The account transaction ID |
| Payment Credit Account | paymentCreditToAccount | Text | Yes | The GL account name for the payment |
| Payment Amount | paymentAmount | Text (currency) | Yes | The original payment amount |
| Credit Amount | paymentCreditAmount | Text (currency) | Yes | The amount of this payment being converted to credit |
| Payment To Account ID | paymentToAccountId | Text | No (hidden) | The GL account ID for internal tracking |
Auto-Allocation Logic
Similar to the Apply Vendor Credit form, payments are pre-allocated when the form loads:
- The system starts with the vendor credit amount as the remaining amount to allocate
- Payments are processed in the order returned by the query (all transactions for the linked bill)
- For each payment:
- If the remaining credit amount can cover the full payment, the payment is selected with its full amount as the credit amount
- If the remaining credit amount is less than the payment amount, the payment is selected with only the remaining credit amount
- Once the credit amount is fully allocated, remaining payments are left unselected with 0.00 credit amounts
Credit To Account Dropdown
Same GL account hierarchy dropdown as in the Apply Vendor Credit form. Loads all active accounts from chart_master grouped by account type with hierarchy indentation. Defaults to the vendor credit's existing CreditToAssetAccount value.
Notes Field
The Notes text box (tbNotes) directly updates VendorCredit.VendorCreditNote as the user types.
Save and Close Behavior
Clicking "Save & Close" sets DialogResult.OK and closes the form. The actual credit processing is handled by the calling code, which reads the CreditedPayments property to get the list of selected payments.
The CreditedPayments property returns a list of CrediteddPayment objects, one for each selected row in the payments grid. Each object contains:
| Property | Type | Description |
|---|---|---|
| PaymentId | int | The account transaction ID of the payment being credited |
| PaymentAmount | decimal | The original payment amount |
| PaymentCreditAmount | decimal | The portion of the payment being converted to credit |
| CreditToAccountId | int | The GL account ID for the credit |
| CreditToAccount | string | The GL account name for the credit |
Loading Sequence
On form load, three data-loading methods run asynchronously in sequence:
- LoadBusinessAccounts() -- Populates the Credit To Account dropdown
- LoadCreditToPayments() -- Loads the payments grid with auto-allocation
- LoadVendorCredit() -- Populates the header fields from the VendorCredit object
A progress indicator with "loading transaction..." text is displayed during this sequence.
Related Articles
- Article 81: Working with Vendor Credits -- Explains vendor credit concepts, how credits are created, applied, reversed, and cancelled
- Article 82: Vendor Refund Workflow -- Covers the refund process when you want money back instead of a credit, including all 12 refund statuses
- Article 78: Purchase Order Statuses and Billing -- Provides context on PO statuses, billing, and where vendor credits fit into the purchasing workflow