Standard Payments & Commission Lifecycle

1. Purpose & Audience

This page defines how standard (non-recurring, non-shared) client payments are recorded in the BackOffice CRM, how commission is calculated, aggregated, and invoiced to Users, and which control mechanisms ensure that all relevant payments are declared and settled correctly.

It is intended for Developers implementing or modifying payment and commission logic, Users (lawyers and other professionals) who must record payments and understand their commission statements, and Admin staff who oversee invoicing, collections, and financial reporting.

2. Scope & Non‑Scope

This section covers:

• Standard client payments declared in the BackOffice Payments tab.
• Commission rate configuration in Laravel and how it is applied to BackOffice payments.
• Monthly/periodic aggregation of commissions and issuance of invoices to Users.
• Control mechanisms ensuring Users declare payments and pay commission invoices on time.
• User and Admin UI elements directly related to standard payment declaration and commission lifecycle.

It does not cover:

• Shared clients, referrals, and split fees (handled in 7.2).
• Recurring services (handled in 7.3).
• Refunds, credit notes, or payments to Users/agencies (handled in 7.4).
• Detailed financial reporting and expenses/disbursements (handled in 7.5).

3. Core Concepts & Definitions

3.1 Payment

A payment is any monetary amount that a client pays to a User (or to AA where applicable) in respect of a specific client record and its associated Enquiry Type (ET). In BackOffice, payments are stored in the Payments tab of the client record and form the basis for commission calculation.

3.2 Commission

Commission is the fee that AA charges a User or provider, calculated as a percentage of the ex‑VAT amount of the payments declared for a client. Commission rates are driven primarily by ET configuration in Laravel, with possible overrides per User and per provider.

3.3 Commission Base (Ex‑VAT)

The commission base is the taxable amount on which AA’s commission percentage is applied. The system assumes that VAT charged by the User to the client is excluded from the commission base. Where a User declares an amount that includes VAT, Admin may need to correct the amount so that only the ex‑VAT portion contributes to commission.

3.4 User vs Admin

A User is a lawyer or other professional who handles client work and records payments in BackOffice. Admin refers to Advocate Abroad internal staff who configure ETs and commission rules in Laravel, create blocking tasks, monitor unpaid commission, and issue or manage invoices.

3.5 Provider / Agency

A provider or agency is an organisation configured in Laravel that can send multiple clients and has its own commission structure and payment/invoicing settings. For standard payments, the logic for calculating AA’s commission per payment is the same, but aggregation and statements can be at provider level as well as per individual User.

4. Data Model Overview

4.1 BackOffice Client & Payments

• Client record: Stores core information (status, ET, country, assigned User, etc.) and references one or more payment records.
• Payments tab: Contains one row per payment declaration with fields such as amount, date, method, notes, and flags for commission calculation.
• Status fields: Overall client status (New Enquiry, In Progress, Completed, Closed, etc.) and automation rules that may depend on payment data.

4.2 Laravel Commission Configuration

• User profile (Laravel > Users): Stores default commission rate and per‑ET overrides for each User.
• ET configuration (Laravel > Enquiry Types): Defines default commission rates per ET, plus recurring and ASP flags.
• Provider profile (Laravel > Providers): Stores commission structures and invoicing settings for agencies and other partners.

4.3 Aggregation & Invoicing Data

• BackOffice aggregates payments per User and period (typically month) into a commission statement.
• Laravel stores commission settings and may also store extracted statistics for reporting and provider-level statements.
• Invoices to Users are generated by AA’s accounting system using the aggregated commission data exported from BackOffice/Laravel.

5. Declaring Standard Payments in BackOffice

5.1 Accessing the Payments Tab

Within a BackOffice client record, the Payments tab is one of the standard tabs in the top tab bar. Only Users and Admin with appropriate permissions can add, edit, or delete payment entries.

5.2 Payment Entry Fields

A typical payment row includes at least the following fields:

• Amount (required): The ex‑VAT fee paid by the client for this client record. If a User enters an amount including VAT, Admin may need to adjust to ex‑VAT.
• VAT / Tax (optional or implicit): VAT amount, if tracked separately. This does not form part of the commission base.
• Total (derived): Sum of amount plus VAT where relevant.
• Date (required): Date the payment was received from the client.
• Payment Method: Dropdown with options such as Bank Transfer, Card, PayPal, Cash, Other.
• Service / ET: If the record has multiple services, indicates which ET the payment relates to. For standard single‑service clients, this may be implicit.
• Notes: Free‑text field for brief explanation (e.g. “50% advance”, “Final payment”, “Additional drafting work”).
• Commissionable flag: Indicates whether this payment should be included in commission calculations (true for standard fees, false for pure disbursements/expenses).

5.3 Validation Rules

• Amount must be a positive number and cannot be zero.
• Date cannot be in the future beyond a reasonable tolerance (configurable per jurisdiction).
• Payment Method is required.
• For certain ETs, at least one payment is required before allowing status changes to Completed or Closed.
• If the commissionable flag is false, the payment is excluded from commission calculations but still counted in client-level totals.

5.4 Status Impact of Payments

When the User has finalised the service being provided to the client and the total commissionable payments declared for a client reaches the agreed fee, Users are expected to move the client status from Ongoing to Completed. Some flows enforce this by presenting a completion popup summarising recorded payments and asking the User to confirm that the amounts match what was actually paid.

In some configurations, adding the first commissionable payment automatically changes the status from Created Lead to Ongoing or similar, to reflect that work has commenced and fees have been received.

6. Commission Calculation Logic

6.1 Determining the Commission Rate

When AA refers a client directly to a User (no prior referral from another User), the standard commission rate is 20% of the net (ex‑VAT) amount paid by the client to that User.

When a client is referred by one User to another User, the standard commission rate for the referred enquiry is 30% of the net amount paid by the client to the “referred to” User. Of that 30%, the “referring” User receives 50% as a referral share (i.e. 15% of the client’s net payment), and AA retains the remaining 15%.

6.2 Commission Base and Amount

For each commissionable payment, the commission base is the ex‑VAT amount declared. The system multiplies the base by the applicable commission rate to compute the commission amount for that payment. Commission amounts are rounded according to local accounting rules (typically to two decimal places).

6.3 Partial and Staged Payments

When clients pay in stages (e.g. provision of funds followed by final payment), Users create a separate payment entry for each amount received. The system calculates commission per payment and accumulates these amounts for the period. If a User mistakenly declares the same payment twice, Admin must remove or correct the extra line; otherwise, commission would be overstated.

6.4 Non‑Commissionable Payments

Some payments, such as pure disbursements or third‑party expenses, are recorded for completeness but should not attract commission. These entries are created with the commissionable flag set to false. They appear in the Payments tab for the client but are excluded from commission summaries and invoices.

7. Control System for Payment Declaration

7.1 Blocking Tasks

Admin can create blocking tasks in BackOffice that prevent a User from accessing other client records until a specific action is completed. One of the main blocking task types is “Add Payment”, which is used when AA knows or strongly suspects that the User has received fundsfrom a client but has not yet declared them in the Payments tab.

When a blocking Add Payment task exists, the User is presented with a popup on login or when opening another client and is redirected to the relevant client record to declare the payment. After they add the payment and mark the task as complete, normal navigation is restored.

7.2 Status Change Checks

When Users attempt to change status to Completed or Closed, the system can display a confirmation popup summarising the total payments recorded for the client. If the User enters a “total paid” that does not match the sum of payments, a warning is shown and the User is encouraged to review the Payments tab before continuing.

In some flows, status change is blocked entirely until at least one payment has been declared, to avoid Completed cases with zero payments.

7.3 Dashboards & Lists Highlighting Missing Payments

Admin dashboards can display lists of clients where:

• Work is clearly underway or Completed but no payments have been declared.
• There is a long gap between initial contact and any payment declaration.
• Blocking payment tasks are overdue.

These lists help Admin identify potential under‑reporting of payments and trigger manual follow‑up with Users.

7.4 Notification Emails to Users

When Admin creates or updates blocking tasks or when commission invoices remain unpaid, the system can send notification emails to Users. Typical notifications include:

• Reminder to add a payment for a specific client.
• Reminder that a commission invoice is overdue.
• Summary of outstanding payment‑related tasks in daily or weekly digests.

8. Commission Aggregation & Cut‑Off

8.1 Aggregation Period

Commission is typically aggregated on a monthly basis, although quarterly or other periods are possible if configured. All commissionable payments with a payment date within the aggregation period and declared before the cut‑off date are included in the statement for that period.

8.2 Cut‑Off Rules

The cut‑off date is the point at which the system stops adding payments to the current period’s commission batch. For example, if invoices are issued on the first Friday of the month, all payments in the previous calendar month that have been declared up to that Friday are included. Late declarations may be carried to the next period or, in special cases, handled by manual adjustment.

8.3 Grouping by User and Provider

The aggregation process groups payments by:

• User (professional) – each User sees a statement of all their commissionable payments for the period.
• Provider/agency – for agency relationships, the system may also produce provider-level summaries according to the provider’s commission structure.

Each group forms the basis for one invoice or statement issued to that party.

9. Invoicing Commission to Users

9.1 Invoice Generation

Certain Enquiry Types have a fixed commission rate of 20% regardless of whether the client came via a referral. For those Enquiry Types, if another User has referred the client, the referrer still receives 50% of the commission, but the split is applied to the fixed 20% rate (i.e. 10% of the client’s net payment to the “referred to” User for the referrer, and 10% for AA).

9.2 Invoice Contents

A standard commission invoice includes at least:

• Invoice number, issue date, and due date.
• Period covered (e.g. “Commission on client payments for January 2026”).
• Total commission amount and applicable VAT.
• Bank account details and any alternative payment methods accepted by AA.

In many cases, a detailed statement is attached or accessible in the User’s dashboard, listing each client, ET, payment amount, commission rate, and commission amount.

9.3 Delivery & User Access

Invoices are delivered via email to the User’s registered address and may be accessible in a “Commission Statements” or similar section of the User dashboard. Users are expected to pay the invoice by the due date using the provided bank details.

9.4 Overdue Invoices

When an invoice is not paid by the due date, the system can:

• Flag the User as having overdue commission.
• Show warning banners in their BackOffice session.
• Generate reminder emails and internal Admin alerts.
• Optionally, trigger restrictions (e.g. reduced capacity for new leads) according to business policy.

10. User & Admin UI Behaviour

10.1 User View

Users interact primarily with:

• The Payments tab on each client to add and review payments.
• Status dropdowns and completion popups that summarise payment totals.
• Commission statements or reports showing historical commission by period, ET, and client.

10.2 Admin View

Admin users have additional views and actions, including:

• Creation and management of blocking Add Payment tasks.
• Dashboards showing potential under‑reported payments, overdue tasks, and unpaid invoices.
• Export tools to pull aggregated commission data from BackOffice/Laravel into the accounting system.
• Ability to correct or reclassify payment lines when Users make mistakes (e.g. VAT included, wrong ET, non‑commissionable items).

11. Edge Cases & Known Pitfalls

11.1 Incorrect VAT Handling

A common issue is Users entering the total amount received from the client, including VAT, as the commissionable amount. This leads to over‑charging of commission. Admin should correct such entries by reducing the commissionable base to the ex‑VAT amount and, if necessary, adjusting any already issued invoices via credit notes (documented under 7.4).

11.2 Duplicate Payments

Duplicate payment rows can occur if a User creates a new payment entry instead of editing an existing one. The system cannot reliably detect all duplicates, so Admin should periodically review payment lists for anomalies (e.g. same amount and date appearing twice) and instruct Users to correct errors.

11.3 Zero or Missing Payments on Completed Cases

If a case reaches Completed or Closed status with no payments recorded, dashboards or reports may highlight it as a potential issue. Admin should follow up with the User to confirm whether the client never paid or whether the payment has not yet been declared.

12. Configuration Points (Laravel)

12.1 Commission Settings per User

In Laravel, each User profile has a Commission Settings section, where Admin can define:

• Default commission rate (applies when no per‑ET override exists).
• Per‑ET commission overrides (e.g. 20% for Property Purchase, 25% for Litigation).
• Referral commission split settings used in shared/referral cases (see 7.2).

12.2 Commission Settings per ET

Each ET configuration in Laravel includes:

• Default commission rate applicable to all Users unless overridden.
• Flags for recurring behaviour and ASP involvement.
• Reporting and exclusion rules that may affect financial dashboards.

12.3 Provider Settings

Provider records in Laravel define:

• Commission structures specific to the provider.
• Linked Users and roles.
• Payment and invoicing settings for statements issued to or from the provider.

13. Process Flow: Lead to Commission

13.1 High‑Level Steps

1. Lead captured and assigned: Website form submission creates a client record in BackOffice with an ET and assigned User; status is New Enquiry or Awaiting Assignment.
2. Service delivered: User communicates with the client, sends quotations, and carries out agreed work. Status moves through Created Lead, In Progress, and Waiting for Response as appropriate.
3. Client payment received: User receives payment from the client (advance, lump sum, or staged) and records each payment in the Payments tab as a commissionable entry.
4. Commission computed: For each commissionable payment, the system determines the applicable commission rate and calculates commission. These values are stored and visible in relevant reports.
5. Status completion: When work is complete and fees have been fully received, the User changes status to Completed and, if applicable, confirms payment totals in a popup.
6. Aggregation & invoicing: At period end, commission amounts per User are aggregated, invoices are generated, and Users receive commission invoices and statements.
7. Payment of commission: Users pay AA’s invoice. Overdue invoices trigger reminders and potential operational restrictions until resolved.

14. Testing & QA Considerations

When implementing or modifying payment and commission logic, testers should verify at minimum:

• Correct commission calculation for different ETs and Users with/without overrides.
• Correct handling of VAT (commission on ex‑VAT amounts only).
• Correct behaviour of blocking Add Payment tasks and their release after completion.
• Accurate aggregation across the intended period and correct inclusion/exclusion of non‑commissionable payments.
• Correct behaviour of status completion popups when payments do and do not match expected totals.
• That invoices produced from aggregated data match the underlying payment records and commission rates.

15. Open Questions & Future Enhancements

• Whether automatic detection of likely duplicate payments should be implemented (e.g. same amount, same client, close dates).
• Whether configurable rules should allow some ETs to bypass payment‑before‑completion requirements under specific circumstances.
• Whether to expose more granular controls for differential commission rates by country or payment method within the same ET.
• Whether to standardise how late‑declared payments are assigned to periods (original payment date vs declaration date) to simplify reconciliation.