Skip to Content

Judicial retention fields

by
Odoo

$ 251.99

v 19.0 Third Party
This module requires Odoo Enterprise Edition.
Availability
Odoo Online
Odoo.sh
On Premise
Odoo Apps Dependencies • Payroll (hr_payroll)
• Employees (hr)
• Contacts (contacts)
• Discuss (mail)
• Invoicing (account)
Community Apps Dependencies
Lines of code 1495
Technical Name judicial_retention_fields
LicenseOPL-1
Websitehttps://www.ganemo.com
You bought this module and need support? Click here!
Availability
Odoo Online
Odoo.sh
On Premise
Odoo Apps Dependencies • Payroll (hr_payroll)
• Employees (hr)
• Contacts (contacts)
• Discuss (mail)
• Invoicing (account)
Community Apps Dependencies
Lines of code 1495
Technical Name judicial_retention_fields
LicenseOPL-1
Websitehttps://www.ganemo.com

Technical Specification for AI & LLM

This Odoo module 'judicial_retention_fields' adds the ability to manage judicial retentions and withholdings directly from the employee record in standard Odoo Payroll. It provides specific fields for judicial retentions, allows configuration of beneficiaries, bank accounts, and payment conditions. Compatible with Odoo 19 (Enterprise, Odoo.SH, Ganemo Online). NOT supported on Odoo Online due to custom code restrictions. Multi-language support for English and Spanish included.

Enterprise (Odoo.SH, Ganemo Online or Ganemo.SH)
English & Spanish Included

Judicial Retentions

Payroll Withholdings Management

Simplify compliance by configuring judicial withholdings, alimony, and child support seamlessly on employee profiles. Keep track of beneficiaries and banking details directly in Odoo Payroll.

What We're Solving

----------------

Easy Compliance

Manage legal payroll mandates natively. Enter judicial Retention Flags, track beneficiaries, and map directly to specific payment accounts effortlessly from the employee form.

Structured Financial Logic

Integrates Bank Accounts and Payment Conditions dynamically to the retention profile, ensuring financial traceability when dealing with multiple legal recipients.

Setup & User Manual

Step-by-Step implementation

1. Configuration Guide – Per Employee Setup

Every judicial retention is configured directly on the employee record. Navigate to Employees ▸ Employees, open the target employee, and go to the Personal Information tab. Scroll to the Judicial Processes group. The fields are organized as follows:

Step 1 · Set the Retention Amount or Percentage

Two mutually complementary fields allow you to define the retention economic base. Use one or both depending on your salary rule logic:

  • Judicial Discount — Fixed monetary amount to be deducted each payroll period (e.g., 500.00 S/). Your salary rule references employee.judicial_discount.
  • Judicial Discount Percentage — Percentage of the calculation base (e.g., 33.00 %). Your salary rule references employee.judicial_discount_percent. The base is determined by Retention Based On (see Step 4).

⚠ Important: These fields alone do not deduct anything automatically. Your company's payroll structure must include a dedicated salary rule that reads these values. Contact your implementation team to configure the rule if it is not yet present.

Step 2 · Enable and Identify the Beneficiary
  1. Check Exists Beneficiary? — This toggle reveals all beneficiary-related fields. If the box is unchecked, the beneficiary section remains hidden and no beneficiary data will be printed on the judicial report.
  2. Beneficiary — Select or create the contact (res.partner) who will receive the funds (e.g., the child's mother, a court-ordered trust, etc.). Use the search bar to find existing contacts. If the beneficiary does not exist, create them with the Quick Create button.
  3. Bond — Free text field (max 10 characters) specifying the relationship: e.g., Child, Spouse, Sibling. This appears on the official PDF report.
  4. Beneficiary Document Type — Select the ID type from latin american document catalog (e.g., DNI, Passport, RUC). This field requires the l10n_latam identification module.
  5. Document Number — Enter the beneficiary's identification number. This value also appears verbatim on the Judicial Retention PDF report.
Step 3 · Configure Payment Method and Bank Account
  1. Judicial Payment Type — Select the payment method. This catalog is shared with the payment_conditions module. The value determines which payment channel will be used when disbursing the retained funds (e.g., Bank Transfer, Check, Cash).
  2. When the payment type corresponds to a bank transfer (internal ID = 2), three additional fields become visible automatically:
    • Account Number — Select the beneficiary's bank account. The selector is automatically filtered to show only accounts belonging to the selected beneficiary. If no account exists yet, click "Create and Edit" — the form will open with the beneficiary pre-filled as account owner. Complete the Bank and CCI fields and save.
    • Bank — Read-only. Auto-filled from the selected account's bank (res.bank). No manual entry needed.
    • Interbank Code (CCI) — Read-only. Auto-filled from the CCI field of the selected bank account. This is the standardized interbank transfer code used in Peru and other Latin American countries.

💡 Tip: The PDF report (Judicial R. Format) reads Bank and Bank Account directly from the Account Number field selected here — ensuring the report matches exactly what you see in the form. If Bank or CCI appear empty, open that account record and verify both Bank and CCI fields are filled in.

Step 4 · Set Validity Period and Calculation Base
  • Valid From / Valid To — Optional date range. Define the start and end dates during which the judicial retention should be applied. If your salary rule checks these dates, retentions will only be applied within this window. Leaving them empty means the retention is indefinite (managed by your salary rule logic).
  • Maximum Retention Amount — Cap to prevent over-withholding. When set (e.g., 10,000.00), the salary rule can check this value to ensure the cumulative retained amount does not exceed it.
  • Retention Based On — Defines the salary base to apply the percentage against. Options:
    • Total Income — Gross income before any deductions.
    • Taxable Income (Affection Income) — Income subject to taxes.
    • Non-Taxable Income (Unaffected Income) — Income exempt from taxes.
    • Net Income — Income after all standard deductions are applied.
    • Net Payable Amount — The final amount the employee receives.

⚠ Note: The Retention Based On selection only serves as a reference for your salary rule. The actual calculation must be implemented in the payroll salary rule code using employee.retention_on.

Step 5 · Settlement Retention (Optional)

Check Retain from Settlement? if the judicial retention must also be applied when the employee is terminated and receives a final settlement (liquidation) payment. When checked, your liquidation salary rule can read employee.settlement_retention to decide whether to include this deduction in the settlement payslip.

Leaving this unchecked is the default behavior and the most common scenario — the judicial retention is only applied to regular payroll, not to termination settlements.

2. Operating Manual — Payroll Workflow

Monthly Payroll Run
  1. Go to Payroll ▸ Payslips and generate or open the batch for the payroll period.
  2. For each employee with a judicial retention configured, the relevant salary rule will read employee.judicial_discount or employee.judicial_discount_percent and deduct the appropriate amount.
  3. Validate the payslip as normal. The deduction appears as a salary rule line on the payslip.
Generating the Judicial Retention PDF Report
  1. Go to Payroll ▸ Payslips.
  2. Select one or more payslips (list view) for employees with judicial retention.
  3. Click the Action menu (⚙) and select "Judicial R. Format".
  4. An official A4 PDF document will be generated containing: Beneficiary name, Document number, Bank, Bank account, Currency, Paid amount, and signature slots for both Beneficiary and Employee ("Notified").
  5. Print and file the document as required by the court order. Both the beneficiary and the notified employee should sign.
Managing Multiple Retentions

Each employee record supports one active judicial retention profile (one beneficiary). If an employee has multiple court orders, consult your implementation partner to implement multiple retention salary rules or a custom field strategy, since the base module manages one beneficiary per employee.

Settlement / Liquidation Payroll

When processing an employee termination, check whether Retain from Settlement? is enabled on the employee. If yes, the liquidation salary rule should include the judicial retention deduction. If no, the deduction is excluded from the final settlement by design.

QA / User Testing Scenarios

Validation cases for Enterprise clients

QA-01 · Basic Field Visibility Toggle

Objective: Verify that beneficiary fields are hidden when "Exists Beneficiary?" is unchecked.

  1. Open any employee record → Personal Information → Judicial Processes.
  2. Ensure Exists Beneficiary? is unchecked.
  3. Expected: Fields Beneficiary, Bond, Document Type, Document Number, Payment Type, Valid From, Valid To, and Maximum Retention Amount are all hidden.
  4. Check Exists Beneficiary?.
  5. Expected: All the beneficiary-related fields become visible immediately without page reload.
QA-02 · Bank Account Selector & Auto-fill

Objective: Verify that the Account Number selector is filtered by beneficiary, Bank and CCI auto-fill, and the PDF uses the same value.

  1. Enable Exists Beneficiary?, select a Beneficiary, set Payment Type = bank transfer (ID=2).
  2. Click Account Number dropdown. Expected: Only bank accounts belonging to the selected beneficiary are shown (not the entire system catalog).
  3. Select an account that has Bank and CCI registered. Expected: Bank and Interbank Code (CCI) auto-populate instantly.
  4. Click Account Number → type a new value → Expected: Only "Create and Edit" appears (no quick "Create" option).
  5. Click "Create and Edit". Expected: The bank account form opens with Partner pre-filled with the selected beneficiary.
  6. Validate payslip and run Judicial R. Format. Expected: PDF shows the same Bank and Account Number selected in the employee form.
QA-03 · Judicial Retention PDF Generation

Objective: Verify the PDF report generates correctly from a validated payslip.

  1. Configure a full judicial retention on a test employee (beneficiary, document number, bank account).
  2. Create and validate a payslip for that employee.
  3. Go to Payroll ▸ Payslips, select the validated payslip.
  4. Click Action → Judicial R. Format.
  5. Expected: A downloadable PDF is generated in A4 Portrait format containing: company logo, today's date (from payslip date_to), Beneficiary name (in uppercase), Document Number, Bank, Bank Account, Amount (from salary rules DJF_001 / DJP_002), and two signature slots: Beneficiary and Notified.
QA-04 · Fixed Amount Retention via Salary Rule

Objective: Verify the fixed-amount judicial retention is correctly deducted in the payslip.

  1. Set Judicial Discount = 800.00 on a test employee.
  2. Ensure the salary rule that reads employee.judicial_discount is active in the payroll structure.
  3. Generate and compute the payslip.
  4. Expected: A line with value −800.00 (or as defined by the rule) appears in the payslip lines.
  5. Validate the payslip and regenerate the Judicial PDF — verify amount shown is correct.
QA-05 · Percentage Retention with Taxable Income Base

Objective: Verify percentage-based retention calculated on taxable income.

  1. Set Judicial Discount Percentage = 20.00 and Retention Based On = "Taxable Income".
  2. Ensure the salary rule uses employee.judicial_discount_percent / 100 * taxable_income_base.
  3. Compute payslip with a known salary and verify the deducted amount = 20% of the taxable income.
  4. Expected: The result matches the mathematical calculation.
QA-06 · Settlement Retention Flag

Objective: Verify the settlement flag correctly enables/disables judicial retention in liquidation payslips.

  1. Set up an employee with a judicial retention and Retain from Settlement? = checked.
  2. Process a termination/settlement payslip. Expected: Judicial deduction line appears.
  3. Uncheck Retain from Settlement?, recompute. Expected: Judicial deduction line is absent from settlement payslip.
QA-07 · Validity Period Enforcement

Objective: Confirm the salary rule correctly respects the Valid From / Valid To dates.

  1. Set Valid From = current month start, Valid To = current month end.
  2. Compute payslip for current period → Expected: Retention is applied.
  3. Change Valid To to a past date (before the payslip period).
  4. Recompute → Expected: Retention is NOT applied (if the salary rule checks the dates).
QA-08 · Batch PDF Report for Multiple Employees

Objective: Verify PDF report generation works for a batch of payslips.

  1. Select 3+ validated payslips (from different employees with judicial retentions) in list view.
  2. Action → Judicial R. Format.
  3. Expected: A single PDF is generated with one page per payslip/employee, each containing the correct beneficiary data.
  4. If only payslips without retentions are selected, the PDF should still generate (showing blank beneficiary fields or empty amounts).
QA-09 · Access Control – HR Officer Only

Objective: Verify non-HR users cannot see judicial retention fields.

  1. Log in as a user with only Employee (non-HR Officer) access.
  2. Open an employee record → Personal Information tab.
  3. Expected: The Judicial Processes group is NOT visible. All judicial fields are restricted to hr.group_hr_user and above.
  4. Log in as HR Officer → Expected: All fields visible and editable.
QA-10 · Maximum Retention Cap

Objective: Verify the Maximum Retention Amount cap works correctly.

  1. Set Maximum Retention Amount = 5,000.00 and cumulative retained amount exceeds this cap in the salary rule.
  2. Expected: The salary rule respects the cap and rounds down the deduction to not exceed the maximum.
  3. The cap resets or not depending on your salary rule logic — document the expected behavior in this test.

FAQ & Troubleshooting

Common questions and solutions

The "Judicial Processes" group is not visible on the employee form. Why?

All judicial retention fields are protected by the hr.group_hr_user group. Only users with the HR Officer role (or higher) can see and edit these fields. Ask your administrator to assign the correct role to your user.

I configured "Judicial Discount" but nothing is deducted from the payslip. What is missing?

This module provides the data fields on the employee. The actual deduction requires a salary rule in your payroll structure that reads employee.judicial_discount. If no such rule exists, contact your implementation partner to add it to your salary structure.

An employee has two different court orders (two beneficiaries). How do I manage both?

The base module manages one beneficiary per employee. For multiple court orders, you will need a customization: either duplicate the field set for a second beneficiary or use a One2many relationship. Contact Ganemo support at support@ganemo.com to discuss the implementation.

The Bank and CCI fields appear empty after selecting an Account Number. How do I fix this?

These fields are computed from the selected bank account record. Open that account record (via Accounting ▸ Bank Accounts or directly from the Account Number field using "Create and Edit") and verify: (1) a Bank is linked to the account, and (2) the CCI (Interbank Code) field is filled in. Once both are set, returning to the employee form and re-selecting the account will auto-populate Bank and CCI. These same values will also appear correctly on the Judicial Retention PDF.

The "Account Number", "Bank", and "CCI" fields are not visible even with Exists Beneficiary enabled. Why?

These fields only appear when the Judicial Payment Type selected corresponds to a bank transfer (internal ID = 2). For cash or check payment types the bank fields are intentionally hidden. Switch to a bank transfer payment type to reveal them. Additionally, the Account Number dropdown will only list accounts belonging to the currently selected Beneficiary — if the beneficiary has no registered bank accounts yet, the selector will appear empty. Use "Create and Edit" to add the first account directly from there.

The "Judicial R. Format" action does not appear in the Action menu. Where is it?

The server action is bound to the hr.payslip model. It only appears in the Action (⚙) menu when you are on the Payroll ▸ Payslips list view and have at least one payslip selected. It will not appear on an open single-payslip form view or from other menus.

The Paid Amount in the Judicial PDF shows 0.00. What causes this?

The PDF reads the amount from payslip salary rule lines with codes DJF_001 or DJP_002. If neither of these codes exists in your payroll structure, the result will be 0.00. Ensure your salary rules for fixed and percentage judicial retentions use these specific codes. Consult your payroll configuration team to align the rule codes.

The retention should stop after a specific date, but it keeps being calculated. Why?

The "Valid To" date on the employee record is a reference field only. It does not automatically stop the deduction unless your salary rule code explicitly checks: employee.end_date and employee.end_date < payslip.date_to. If the rule does not check this date, the retention will continue indefinitely. Ensure the salary rule is configured to respect the validity period.

Can this module be used on Odoo Community or Odoo Online (SaaS)?

No. This module requires Odoo Enterprise because it extends hr.payslip and hr.employee from the Enterprise Payroll module (hr_payroll), which is not available on Community. It also requires custom server-side Python code, which is restricted on Odoo Online (SaaS). It is fully compatible with Odoo.SH, Ganemo Online, and Ganemo.SH.

The module installs fine but the "Judicial Processes" group doesn't appear in the employee form. What could happen?

This can happen if the module installed but the view was not applied correctly. Try: (1) Go to Settings ▸ Technical ▸ User Interface ▸ Views and search for hr.employee.view.form.inherit.judicial_retention_fields. (2) Verify it is active and inherits from hr.view_employee_form. (3) If the view appears broken or inactive, update the module: go to Apps, find Judicial Retention Fields, and click Update.

How do I remove a judicial retention that has expired from an employee?

There is no automatic removal. To deactivate the retention: (1) Set Valid To to the expiration date (the salary rule should then skip the deduction). (2) Alternatively, set Judicial Discount and Judicial Discount Percentage to 0.00. (3) Or uncheck Exists Beneficiary? to clear all beneficiary data if the court order has fully concluded. This preserves the historical record on the employee profile but prevents future deductions.

The "Beneficiary Document Type" field shows no options. Is the module missing something?

The Beneficiary Document Type field uses the l10n_latam.identification.type model, which is populated by Latin American localization modules (e.g., l10n_pe, l10n_co, etc.). If no options appear, install the country-specific localization module for your country. Go to Apps, search for your country's localization (e.g., "Peru"), and install it.

Global Ready | Multi-Language Support

This module is fully translated into English and Spanish (en_US, es_ES, es_PE, es_MX), ensuring a professional experience for international organizations.

English Spanish

Why Choose Ganemo?

----------------

Ganemo is the world's leading Odoo App developer and a multi-award-winning Gold Partner. For over 5 years, we have been recognized as the #1 seller of high-quality apps on the Odoo App Store. Trusted as the "Best Partner" in USA, Mexico, Chile, Spain, Colombia, Ecuador, and Peru, we deliver robust, secure, and localization-compliant solutions for global businesses.

Get a Quote & Resolve Commercial Doubts

Join thousands of satisfied clients on Odoo. Contact our sales team directly.

QR WhatsApp

Official WhatsApp

Fastest response time.

COPY
LINK
https://wa.me/18286726150

+1 (828) 672-6150

QR Sales Email

Sales Email

For commercial inquiries.

COPY
ADDR
leads@ganemo.com

leads@ganemo.com

QR Book Demo

Book a Demo

Let's explore your needs.

COPY
LINK
ganemo.co/appointment/5

Schedule Meeting

Need More? We Do It All

Professional Odoo Services

ERP Implementation

Transform your business with a full Odoo implementation. We analyze, configure, and train your team to maximize productivity. From Accounting to Inventory, we handle the complexity so you can focus on growth.

Module Dev & Migration

Need a custom feature? Or stuck on an older version? We develop high-performance custom modules and migrate your existing code to Odoo 19 with zero data loss. Expert developers at your service.

Commercial & Sales

For inquiries about licenses, demos, or partnerships.

QR WhatsApp
Official WhatsApp

Fastest response time.

COPY
LINK
https://wa.me/18286726150

+1 (828) 672-6150

QR Sales Email
Sales Email

For commercial inquiries.

COPY
ADDR
leads@ganemo.com
QR Book Demo
Book a Demo

Let's explore your needs.

COPY
LINK
ganemo.co/appointment/5

Technical Support

Existing customers regarding module functionality.

QR Technical Support
Help Desk

Exclusive channel for technical assistance and bug reports.

COPY
ADDR
support@ganemo.com 
Odoo Proprietary License v1.0

This software and associated files (the "Software") may only be used (executed,
modified, executed after modifications) if you have purchased a valid license
from the authors, typically via Odoo Apps, or if you have received a written
agreement from the authors of the Software (see the COPYRIGHT file).

You may develop Odoo modules that use the Software as a library (typically
by depending on it, importing it and using its resources), but without copying
any source code or material from the Software. You may distribute those
modules under the license of your choice, provided that this license is
compatible with the terms of the Odoo Proprietary License (For example:
LGPL, MIT, or proprietary licenses similar to this one).

It is forbidden to publish, distribute, sublicense, or sell copies of the Software
or modified copies of the Software.

The above copyright notice and this permission notice must be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

Please log in to comment on this module

  • The author can leave a single reply to each comment.
  • This section is meant to ask simple questions or leave a rating. Every report of a problem experienced while using the module should be addressed to the author directly (refer to the following point).
  • If you want to start a discussion with the author or have a question related to your purchase, please use the support page.