> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Consignado privado

> Payroll-deducted lending in Brazil: the vocabulary, where the commercial terms come from, the collateral model, and the averbação lifecycle topics.

**Consignado privado** is payroll-deducted private-sector lending. The paying employer withholds each installment at source, from the borrower's salary. It works as a full Brazilian bounded context on top of the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack). It has its own vocabulary, its own collateral model, and its own lifecycle topics.

## The vocabulary

***

| Term            | Gloss                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| **Consignado**  | Payroll-deducted credit — repayments are withheld from salary at source.                                |
| **Averbação**   | Registration of the payroll deduction with the paying entity, so installments are withheld each period. |
| **Margem**      | The consignable margin — the portion of salary available for deduction.                                 |
| **Vínculo**     | The employment link between borrower and employer that the loan is deducted against.                    |
| **Competência** | The payroll period (a `YYYYMM` reference) an installment is deducted in.                                |
| **CCB**         | *Cédula de Crédito Bancário* — the bank credit instrument for the loan.                                 |

## Where the commercial terms come from

***

Your credit engine prices a consignado loan. The rate, the annual rate, the CET, the IOF and the installment plan are contracted facts Lender records, never values Lender computes. Lender binds those terms to a loan product version.

Money and rate fields cross the wire as decimal strings (never floats), consistent with the ledger's money model.

## Optional collateral (garantias)

***

A consignado contract can carry FGTS and rescission-benefit collateral alongside the payroll deduction. A contract either declares collateral and carries at least one of the three amounts, or declares none and carries none.

| Field                              | Meaning                                                    |
| ---------------------------------- | ---------------------------------------------------------- |
| `valorSaldoDisponivelGarantiaFgts` | FGTS balance amount pledged (from *consultar-saldo-fgts*). |
| `valorMultaRescisoriaGarantiaFgts` | FGTS rescission-penalty amount pledged.                    |
| `percVerbaRescisoriaGarantia`      | Fraction of severance-verbas pledged, capped at `0.35`.    |

The two FGTS fields are money amounts (decimal strings, scale 2). The verbas fraction uses a decimal string (scale 8). Lender validates each field.

Collateral is off-balance: FGTS balances stay in CAIXA custody and never post to the ledger. Lender tracks the pledge as a domain record on the contract, not as a Midaz posting.

## The rail lifecycle

***

The Dataprev rail combines authenticated HTTP commands with asynchronous business facts. On `develop`, the Consignado HTTP API admits averbação. The gateway does not consume an averbação command from the Lender stream.

* Lender commands use `lerian.streaming.lender.commands`.
* Consignado facts use `lerian.streaming.consignado-gw`.
* Event identity comes from source-qualified CloudEvent headers, not from a per-event topic.

| Event key                                                                                   | Direction | Runtime behavior                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consignado.redirecionamento.requested`                                                     | out       | The gateway executes the command when an adapter is wired and returns a named refusal otherwise.                                                                                                            |
| `consignado.exclusao.requested`                                                             | out       | The gateway resolves the same idempotent exclusion service as HTTP; when the runtime is unavailable it returns a named error.                                                                               |
| `consignado.contract.registered` / `consignado.disbursement.confirmed`                      | in        | Booking and proof-of-payment facts.                                                                                                                                                                         |
| `consignado.averbacao.rejected` / `consignado.employment_status.reported`                   | in        | Rejection and employment-status facts.                                                                                                                                                                      |
| `consignado.redirecionamento.confirmed` / `consignado.redirecionamento.rejected`            | in        | Redirection outcomes.                                                                                                                                                                                       |
| `consignado.exclusao.confirmed` / `consignado.exclusao.rejected`                            | in        | Exclusion outcomes.                                                                                                                                                                                         |
| `consignado.reconciliation.received`                                                        | in        | Payroll bookkeeping, CEF repasse, portal CSV, or guarantee-recovery reconciliation.                                                                                                                         |
| `consignado.contract_correction.available` / `consignado.disbursement_correction.available` | in        | The gateway publishes authenticated pointers to corrected CCB or payment resources; Lender retrieves and verifies their SHA-256 digests.                                                                    |
| `consignado.portabilidade.efetivada` / `consignado.portabilidade.rejeitada`                 | in        | When the outcome consumer is enabled and the deployed gateway manifest declares the event, origin-side portability exclusion outcomes close servicing after effectuation or preserve the published refusal. |

Use the [Consignado API reference](/en/reference/rails/consignado/fetch-consignado-worker-margin) for rail commands and queries. The producer and consumer contracts live in [Lender events](/en/products/lender/lender-events) and [Consignado events](/en/reference/events/consignado).

## Contracting gate

***

`CONSIGNADO_ENABLED` defaults to `true`. The contratação route, its CCB signer, and the inbound averbação-confirmed consumer are retired. This setting now gates only the legacy inbound averbação-rejected handling. Servicing for existing contracts remains available. When you disable it, also keep `CONSUMER_CONSIGNADO_AVERBACAO_REJECTED_ENABLED` off. Startup rejects that contradictory configuration. The replacement booking and payment flows configure independently.

## Optional: reconciliation with Matcher

***

This integration is configuration-gated and requires Matcher to use `STREAMING_CLOUDEVENTS_SOURCE=matcher`. Lender then consumes `match_run.completed` from `lerian.streaming.matcher` and routes `ce-source: matcher`, `ce-type: studio.lerian.matcher.match_run.completed`, `ce-resourcetype: match_run`, and `ce-eventtype: completed`. If Matcher uses another source, inspect its streaming manifest and align both sides before enabling the integration. The handler translates the verdict into a PDD stage transition and the corresponding ledger posting intent.

## Next steps

***

<Card title="Brazil regulatory pack" icon="brazilian-real-sign" href="/en/products/lender/brazil-regulatory-pack" horizontal>
  CET, IOF, capitalization consent, PDD staging, and the rest of the BR profile.
</Card>

<Card title="Lender events" icon="tower-broadcast" href="/en/products/lender/lender-events" horizontal>
  The wire contract, the topics Lender publishes, and how a handler stays safe.
</Card>