Employee Payout

Prerequisites

Before creating and working with the Employee Payout, ensure that the Vehicle Invoice ,Route Addition and Schedule Addition have been created successfully.

The Vehicle Invoice is automatically generated from the Vehicle Run Summary. It consolidates all financial components such as trip billing, advances, expenses, penalties, and payouts into a single structured record for review and payment processing.

The Schedule Addition module is a key part of the ERPNext Vehicle Trip Tracking system. It allows users to create detailed daily schedules based on predefined trip schedules and routes, including timing slots and operational responsibilities.

Workflow States

• Pending Entry: Initial stage of the document after creation.
• Pending Verification: Document details are under verification.
• Pending Approval: Awaiting authorization from the designated approver.
• Approved: Document has been verified and is ready for payment processing.
• Rejected: Document has been rejected and requires revision or cancellation.
• Paid: The full payout amount has been processed and cleared.
• Partly Paid: A portion of the total amount has been paid, with the remaining balance pending.

Creating Employee Payouts

1. Employee Payouts are automatically generated once the Vehicle Invoice is submitted and approved, provided the payable amount is greater than zero.
2. To create Employee Payouts manually:
   • Open the respective Vehicle Invoice record.
   • Select Create → Employee Payout.
   • The system automatically generates a payout entry for each employee involved, with pre-filled details such as employee name, invoice reference, route, schedule, and payable amount.
3. If an Employee Payout already exists for the same employee and invoice, the system updates the existing record instead of creating a duplicate.

Employee Payout Form Fields

• Invoice Entry Date: Automatically set at the time of document creation.
• Invoice ID: Reference link to the related Vehicle Invoice.
• Employee: Name of the employee receiving the payout.
• Amount: Total amount to be paid to the employee.
• Pending Amount: Displays the outstanding balance if partial payments are made.
• Expense Claim: Reference to the associated Expense Claim, if applicable.
• Company Bank Account: Specifies the bank account through which payments will be processed.
• Route and Schedule: Indicates the onward and return trip route and schedule associated with the payout.

Actions and Buttons

Validation and Approval

• The system ensures that no duplicate payout is created for the same employee and vehicle invoice.
• Consistency checks are performed to validate employee details, payable amounts, routes, and schedules with the associated Vehicle Invoice.
• Linked Expense Claims must be approved before the payout can be submitted for payment.
• The company bank account field is mandatory to enable payment processing.
• Expense Claim and Employee Payout amounts must match to ensure accurate disbursement.

Payment and Status Updates

• Once the payment is processed, the system automatically updates the Pending Amount based on the amount disbursed.
• Depending on the payment progress, the workflow status transitions automatically as follows:
  • Paid: All dues have been cleared.
  • Partly Paid: Only a portion of the amount has been paid.
  • Unpaid: Payment is yet to be made.
• Status and amount updates are system-driven and require no manual intervention.

Bulk Payment Processing

The system supports bulk payment processing to handle multiple employee payouts simultaneously. It groups payouts by employee and creates corresponding Outward Bank Payments in a single batch, ensuring faster and more efficient payment operations.

Typical User Flow

1. Vehicle Invoice is approved and reflects the payable amount.
2. User navigates to the Vehicle Invoice and selects Create → Employee Payout.
3. System generates payout entries for each associated employee with pre-filled data.
4. User verifies and adds the company bank account details if required.
5. User clicks Create Outward Bank Payment to initiate the payment process.
6. Payments are processed and the system automatically updates the status to Paid or Partly Paid based on the transaction completion.

System Highlights

• Ensures one payout per employee per invoice, avoiding duplication.
• Performs end-to-end data consistency checks across invoices, claims, and payment entries.
• Provides automatic synchronization between payment status and workflow state.
• Integrates seamlessly with Outward Bank Payment for digital disbursement.
• Supports both single and bulk payout creation for operational flexibility.

Technical Flow

This section explains the internal workings of the Employee Payout module, covering server-side logic, validation checks, workflow, and integration with related modules. New developers can use this to understand and safely modify the code.

1. Document Creation

• Employee Payout records can be generated automatically when a Vehicle Invoice is submitted and approved with a positive payable amount.
• Manual creation is possible by navigating to a Vehicle Invoice and using Create → Employee Payout.
• During creation, the system checks for existing payouts for the same employee and invoice to prevent duplicates.

2. Validation Workflow

• Duplicate Check: Ensures no payout exists with the same employee and invoice combination. Throws DuplicateEntryError if found.
• Vehicle Invoice Validation: Confirms employee, amount, route, and schedule details match with the linked Vehicle Invoice. If mismatch occurs, a validation error is thrown.
• Expense Claim Validation: Ensures an associated Expense Claim exists and the amount matches the payout amount. Expense Claim must be approved before submission.
• Bank Account Validation: Mandatory company bank account must be provided for payment processing.

3. Approval and Submission

• On submission (on_submit), the system:
  1. Validates account details.
  2. Approves the linked Expense Claim if the logged-in user is the designated approver.
  3. Updates the pending amount equal to the total payout amount.

4. Payment Integration

• The module integrates with Outward Bank Payment (OBP) through the create_obp method.
• Payment details include the employee, company, bank account, amount, and reference to the Expense Claim.
• References are dynamically fetched from Payment Entry linked to the Expense Claim.
• Supports both single and bulk OBP creation:
  • Bulk processing groups Employee Payouts by employee and creates a single OBP per employee.
  • Pending amounts and references are aggregated for bulk payments.

5. Status and Workflow Management

• The pending_amount field tracks remaining balance for each payout.
• The workflow_state field automatically updates based on payment activity:
  • Paid → pending_amount = 0
  • Partly Paid → partial payment made
  • Unpaid → no payment done yet
• System handles status updates automatically without manual intervention.

6. Client-side Behavior

• Custom buttons and queries are defined in the JS file:
  • Outward Bank Payment button: Appears when workflow_state is not 'Paid'.
  • Clicking this button calls create_obp server method and routes to OBP form.
  • Company bank account field is filtered to show only accounts belonging to the selected company.

7. Key Methods and Functions

• validate: Runs on creation and update. Performs duplicate check, vehicle invoice and expense claim validation, and sets missing dates.
• on_submit: Called when the document is submitted. Handles approvals and pending amount update.
• create_obp: Generates Outward Bank Payment for a single payout.
• bulk_process_create_obp: Handles bulk payout processing for multiple employees.
• validate_route_and_schedule: Ensures route and schedule match between payout and vehicle invoice.
• update_pending_amount / set_status: Updates payment tracking fields and workflow_state.

8. Data Flow Overview

1. Vehicle Run Summary → Vehicle Invoice creation
2. Vehicle Invoice → Employee Payout generation
3. Employee Payout → Expense Claim validation & approval
4. Employee Payout → Outward Bank Payment (single or bulk) creation
5. OBP processed → Pending Amount and Workflow State updated in Employee Payout

Following this flow ensures data consistency across invoices, claims, payouts, and payments, and helps new developers safely extend or modify the module.