Documentação

English

Português
Español

English

Português
Español

Appearance

Payroll ​

Access prerequisites

  • Permission (module): processPayroll (controls UI buttons) + manageCompanyCharges (create/edit/delete) or viewCompanyCharges (list only) — required by the backend
  • License/Feature: None specific.
  • Menu container: GENERAL → Charges group (route /manage-payroll)

What it is / when to use ​

Payroll schedules recurring monthly payments from the company to a user/employee — it is the inverse operation of user charges: here money leaves the company owner's account (userIdFrom) and enters the employee's account (userIdTo), every month, on the configured day, until the final competency date.

Use it for salaries, pro-labore, grants, fixed transfers, and any periodic payment to collaborators. Each entry creates a monthly schedule; a scheduler in CustomerProfileService (CPM) runs periodically and processes each pending installment — via digital account (when the currency is BRL and the DIGITAL_BANKING_CHARGES feature is enabled) or via wallet transaction (token, or BRL without the banking feature).

Prerequisites ​

  • Permission: processPayroll registered for the role (enables the Add payment, edit, and delete buttons in the UI). The backend validates manageCompanyCharges for mutations and viewCompanyCharges/manageCompanyCharges for listing. Dual permission — CPM enum + dynamic module in the DB.
  • License/Feature: None specific. The BRL payment behavior depends on the DIGITAL_BANKING_CHARGES feature being enabled for the tenant.
  • Dependencies on other screens: the employee must exist and have valid wallet/account; the company owner is automatically resolved by the backend as the payer. The target user must be APPROVED.

Step by step ​

  1. Go to Charges → Payroll (route /manage-payroll).
  2. Use the search to filter the list by name or email (local filter).
  3. Click Add payment to open the modal.
  4. Enter the employee's Email, Description, Day (1–31), Month and year of the last payment, and Amount.
  5. Confirm. The system validates the email (looks up the user by wallet), calculates the first payment date and the expiration date, and saves the schedule.
  6. To modify, use the pencil icon; to remove, use the trash icon (opens a confirmation bottom-sheet).

Fields (scheduling modal) ​

FieldWhat it isRequired?System/backend effect
EmailEmployee email to be paidYes (valid email)The screen looks up the user via getUserByEmailWallet. If not found, displays an error and does not save. The returned id becomes the schedule's userIdTo.
DescriptionPayment identifier (e.g., "June Salary")Yes (alphanumeric)Saves description; appears in the statement/transaction.
DayDay of the month on which the payment occursYes (1–31)Defines the recurrence day. Rule: if the chosen day has already passed in the current month, the first payment is scheduled for the following month; non-existent days (e.g., 31 in a short month) are adjusted to the last day of the month.
Month / Year of last paymentFinal competency of the payrollYesComposes the expirationDate. The system prevents dates in the past (errorInLastDate validation).
AmountMonthly payment amountYesSaves amountRequested. Treated as BigNumber during processing. Displayed in the list with the tenant's fiat currency.

The default currency for payroll calls is BRL. The schedule inherits the start (creationDate, calculated from the Day) and end (expirationDate, from Month/Year) fields.

Actions and modals ​

  • Add payment: opens UserPaymentScheduleModalComponent. Confirm is only enabled with a valid form, existing email, and non-past end date → POST /v1/company-charges/createAdmin. The backend sets the payer (userIdFrom) as the company owner.
  • Edit (pencil): opens the same pre-filled modal → POST /v1/company-charges/updateAdmin.
  • Delete (trash): opens a confirmation bottom-sheet; upon confirmation, calls POST /v1/company-charges/deleteAdmin and reloads the page.

Step-up / MFA

Payroll operations are sensitive financial transactions. Depending on the tenant configuration, payment actions may require step-up (password + MFA re-authentication, X-Step-Up-Token header, 5-minute window). If prompted, complete the re-login before the operation is submitted.

Business rules / considerations ​

Attention

  • The email must correspond to an existing user — otherwise the screen blocks saving.
  • The end date cannot be in the past; the screen validates and prevents confirmation.
  • The Day defines the first competency: days already past in the month push the first payment to the following month; 29/30/31 in short months are adjusted to the last day.
  • Payroll pays the employee (deducted from the owner). Do not confuse it with charges that debit the user.

Recurring financial transaction

Each payroll installment transfers real money from the owner to the employee. Review the amount, day, and final competency before saving — installments already paid are not reversed by deletion.

  • Financial amounts: treated as BigNumber in the scheduler — no rounding; verify the currency/token decimal places.
  • Idempotency: each installment uses an externalId equal to the id of the payment schedule. On reprocessing after a crash, FinLib returns E00021 ("already processed") — success, not an error: the amount has already been paid and the installment is marked as applied.
  • APPROVED status: the employee must be approved to receive funds (wallet or digital account).

Examples ​

Scenario 1 — Monthly salary in BRL via digital account

Company with DIGITAL_BANKING_CHARGES enabled registers employee joao@empresa.com, description "Salary", day 5, last payment December/2026, amount R$ 4,500.00. If today is the 10th, the first payment falls in July (day 5 has already passed). Each month until December, the scheduler (CPM) credits R$ 4,500.00 from the owner's account to João's digital account via BMS giveUserBalance.

Scenario 2 — Pro-labore in token

Employee is paid in token (currency other than BRL, or with DIGITAL_BANKING_CHARGES disabled). Each installment becomes a wallet transaction from the owner to the collaborator's wallet, for the defined amount and description. Useful when payment is made in a digital asset rather than a bank account.

Scenario 3 — Adjusting a collaborator's amount

HR increased the salary. The operator opens the entry via the pencil, adjusts the Amount, and confirms. The schedule is updated (updateAdmin) and upcoming installments use the new amount; installments already paid remain unchanged.